Repository navigation
v0.22.0
What's changed
Added
-
Grok Build CLI (
xai-grok) as a fifth backend, joining Claude Code, GitHub Copilot,
OpenAI Codex, and OpenCode. Install thegrokbinary, sign in withgrok login, then
ralphctl settings apply-preset grok-only(or pickxai-grokper flow). Catalog models
aregrok-4.6(flagship) andgrok-4.5. Doctor cannot check Grok login (no auth-status
command). Readiness writes the sharedAGENTS.md(same file as Codex and OpenCode; later
writes keep a.bak.<timestamp>copy). Skills/agents live under.grok/. No
grok-economic / fast / frontier / strong-gate presets; mixed was not rerouted onto Grok.Read-only flows deny edit and shell, while creating a file stays possible so
signals.json
can land. Grok has nowritetool βWriteandEditare aliases ofsearch_replace, the
only tool that can create a file β so the edit gate is the permission rule--deny 'Edit(./**)',
rooted at--cwd: the repo (or per-task worktree) is edit-denied while the session
directory outside it, wheregrok-prompt.mdandsignals.jsonlive, stays writable. Shell
is gated twice, by removing both tool spellings (run_terminal_command,run_terminal_cmd)
and by--deny 'Bash(*)', so a renamed tool id cannot slip through. A no-network session
also removesweb_search/web_fetch, and any closed gate adds--no-subagents. Grok has
no--add-dirβ extra roots stay a named over-grant (--sandbox offis forced so operator
config cannot re-enable a workspace sandbox, and the edit rule is cwd-rooted, so an extra
root stays writable even in a read-only flow). Because that edit rule is rooted at--cwd, a
RALPHCTL_HOMEpointed inside the repo would putsignals.jsonunder it; the adapter detects
that topology, drops the rule rather than blocking the envelope, and logs the over-grant β a
read-only flow there runs edit-capable. Both Grok surfaces now pass--trust:
without it Grok skips theAGENTS.mdand.grok/skillsthat ralphctl itself writes. Grok's
folder trust is one grant, though β it also enables a checkout's own project permission
rules, hooks and repo-local MCP/LSP servers, exactly as opening that repo in Grok yourself
would, and Grok persists the decision in its trust store per folder (the repo and every
per-task worktree path a run uses). Run ralphctl on Grok only against checkouts you would
trust in Grok. Grok's flag surface and permission semantics are verified against
Grok Build CLI 1.0.30's shipped CLI reference (2026-09-15); the minimum supported version is
1.0.13, where the interactive-slands.One thing an interactive Grok session leaves on disk is worth knowing about: it writes
grok-debug.logbeside the session's other artifacts β astdio: 'inherit'child hands
the terminal over and the harness can observe nothing about it, so when a session
misbehaves that log is the only account of what happened, and it is pruned with the rest
of the unit. -
ralphctl sprint reopen <id>β the deliberate exit from an otherwise-terminaldone
sprint. Lands it back inreview(idempotent β an already-reviewsprint passes through
unchanged) and enforces the same single-active-per-project invariant assprint activate, so
a reopen can't collide with a sprint already live on the project.sprint closealso gained
-y/--yesto skip its new confirmation (see Changed) non-interactively. -
Blocked work is now visible everywhere an operator looks, not just the task it happened to.
Home's status card, the sprints list, the cross-project sprint picker, sprint-detail's header,
the settled-run summary, and theNext stepsblock all now show a blocked count β including
once a sprint isdone, since unblocking there reopens it (see Changed) rather than leaving the
count meaningless. Sprint-detail gets aBchord that cycles the cursor to the next blocked
item;u(unblock) is now reachable from the Execute view's own tasks panel, not only
sprint-detail and the sprints list, and once a run settles with a task left blocked the Execute
view's hint strip names that chord instead of leaving it discoverable only through the?
overlay; and a blocked card can no longer be windowed off-screen. The Flows menu stops
disagreeing with every other surface about an all-blocked sprint: where it used to advise
running Plan for a sprint that already has a full task list β a flow the menu doesn't even offer
atplanned/activeβ it now says that every remaining task is blocked and unblocking one
makes it runnable again. On the CLI,sprint progressgroups blocked tasks by root cause
instead of listing a whole cascade as equal-weight rows β an upstream-blocked chain collapses
under the task that's actually broken, each with its reason and aralphctl task unblock <id>
hint β andtask listprints a blocked task's reason plus a recovery hint the same way. -
The generator can say what, specifically, it's stuck on. The
task-blockedsignal gains
optionalblockerClass(missing-information/ambiguous-request/
contradictory-information),question(the one thing that, answered, unblocks it), and
whatUnblocksMe. When the generator supplies them they're persisted on the task and shown
alongside the reason in bothralphctl task listand the TUI, instead of free-form reason
prose being the only clue. All three are optional β a plain reason-only block still works. -
A block now raises a banner and an OS notification the moment a task is saved as
blockedβ whether an attempt settled that way, a parallel task's worktree could not be set up,
its branch hit a fold conflict, or a resumed run found the task's attempt budget already spent.
Previously the only signs were the Tasks panel andprogress.md, which meant an unattended run's
most common failure mode was also its quietest.
Changed
-
Both doors to
donenow confirm before closing over blocked work, naming the tasks.
Closing a sprint has always been able to proceed with blocked tasks left in it β that's still
true, this is a confirm, not a refusal β but neither path used to say so.sprint close(the
TUI launcher and the CLI command) and the review flow's auto-done transition (an empty or
repeated feedback round) both now load the sprint's tasks and, if any are blocked, ask first. In
the TUI the pre-flight confirm folds in a blocked/todo count and the in-chain gate names each
one; on the CLI,sprint closeprompts with the same names (-y/--yesskips it) and, once
the close proceeds either way, prints which tasks stayed blocked and how to recover them. -
Unblocking a task now archives its history instead of erasing it. A clean restart still
resets the attempt budget and drops the block classification and escalation stamps, exactly as
before, but the cleared attempts, per-criterion verdicts, and escalation stamps are now packaged
into one entry on the task's newretiredAttemptslist rather than discarded β so
ralphctl runs statsand the TUI's outcome card keep counting a task's full attempt history
after an operator intervenes, not just what happened since the last unblock. The archive survives the
revived task passing, andruns statsfolds those runs into everything it reports: a task that
failed three times, was unblocked and then passed counts as a four-attempt task, not a first-pass
one, and a retired attempt's model and effort rungs count as granted and fell-through, so the
attempt totals, the first-pass rate and the escalation rows no longer disagree about a task that
was unblocked. Existingtasks.jsonfiles load unchanged; nothing
needs migrating. -
Unblocking a task on a
donesprint reopens it (doneβreviewβactive) instead of
reviving a task with nowhere to run β closing a sprint with blocked work is a legitimate
descoping call, but it shouldn't make that work permanently unreachable if someone later
supplies what it needed. The reopen obeys the same single-active-per-project invariant
sprint reopendoes, rather than walking around it: when another sprint of the project is
alreadyactiveor inreview, the task is still revived but the sprint staysdone, and the
operator is told so: the CLI prints a note naming the peer that holds the project and the
ralphctl sprint closethat releases it, sprint-detail'suappends the same reason to its
toast, and the Sprints list's bulkucounts how many sprints stayed closed instead of
reporting N/N. Whenever an unblock does reopen a sprint, the CLI and the TUI toast say so
(done β active). A reopen that fails for any other reason (the sprint can't be read or saved)
fails the unblock and leaves the task blocked, so a plain retry works. Unblocking a task that is
alreadytodonever reopens a closed sprint β nothing is revived, so the close stands. Two sprints of one project can never both hold the working tree β their repo locks
key on the sprint directory, not the project, so they would not mutually exclude. -
Prompt templates reworked against Anthropic's prompt-engineering guidance. New shared
partials β instructing autonomous operation (decide and proceed instead of asking a question
nobody is there to answer; a turn that ends on a plan instead of the tool calls that execute it
is indistinguishable from a turn that did nothing), batching independent tool calls in one turn,
bounding how much command output gets quoted versus written to a file, an evaluator
failure-modes checklist (resist being talked out of a finding, rubber-stamping a green verify
script, and inventing a defect with no evidence), and a mid-run evaluation-checkpoint shape β
now backimplement,implement-continuation,evaluate,evaluate-continuation, and
reproduce; task-field and task-sizing guidance is likewise shared betweenplanandideate
instead of duplicated. A generator or evaluator session should read as noticeably less prone to
stalling on a question, and more exacting about evidence. -
The nine bundled skills that documented signals via
<note>/<decision>angle-bracket
tags now teach the actual contract: typed objects insignals.json. The tags were never
parsed by the harness β a skill following that guidance produced a tag nothing read. The
skill-contract checker gained a rule (S7) that flags the old tag syntax in any SKILL.md, bundled
or operator-authored, so the mistake can't ship silently again. S7 matches only the tag syntax
it's after: generic type parameters likeArray<Change>,Set<Note>orPromise<Evaluation>
in a TypeScript- or Java-oriented operator skill no longer raise a spurious "skill contract
violation" warning.
Fixed
-
A dirty working tree asks instead of killing the launch. Implement ran two dirty-tree checks:
a hard gate before the setup script that aborted the run outright, and the interactive keep /
stash / reset / cancel menu after it. The hard gate waived only one narrow case β a task still
in_progresswith a running attempt β so a tree left dirty by a cancelled run, or by a task an
operator unblocked (which archives the very attempts that waiver keyed on), failed the launch
before the menu that would have resolved it ever appeared. The hard gate is gone and the menu now
runs before the setup script, right after branch resolution: every question the run has for you is
asked up front, and the multi-minute setup script runs against a tree you already settled. If the
setup script itself changes the tree (a rewritten lockfile, generated files that aren't ignored),
the same menu comes back for those changes, naming the script β otherwise they would have been
swept into the first task's commit. A setup script that leaves the tree alone adds no prompt, and
changes you already chose to keep aren't asked about again. -
Sprint detail's lower half is reachable again on a normal-height terminal. The view hands
β/β to its own card cursor, which left the page itself with no keyboard scroll at all β so on
any terminal where the banner and header cards already fill the viewport, the whole Tasks
section sat below the fold, the cursor walked through rows nobody could see, and the new
Bjump-to-next-blocked chord looked like it did nothing. The page now follows the focused
card: whichever card holds the cursor registers itself with the scroll region, which scrolls
exactly as far as it takes to bring it into view and no further, so a deliberate mouse-wheel
scroll is never fought. Pressingbfor the compact banner is no longer a prerequisite for
seeing your own tasks. -
Action results on sprint detail are pinned instead of scrolling away.
β unblocked "β¦"was
rendered inside the page body, at the tail of the Tickets pane β which on an overflowing view
is below the fold, so unblocking a task appeared to do nothing at all. The message now sits in
the shell's pinned status row next to the banner stack. This matters most for the case it was
added for: unblocking a task on a closed sprint whose reopen the single-active-per-project
check refuses reports that the task was revived but its sprint stayed closed, and that note was
exactly the one nobody could see. It also now leads withβrather thanβ, because a tick in
front of "cannot reopen sprint" reads as "all done" when the operator still has work to do. -
The breadcrumb's sprint status chip no longer goes stale on sprint detail. Home and Flows
both re-stamp the cached status from every snapshot they load; sprint detail did not β and it
is the one view that transitions the sprint under you, since unblocking a task on areview
sprint reopens it toactive. The header card read ACTIVE while the breadcrumb still claimed
REVIEW. -
The Baseline card no longer reports a negative age.
β Pre verify -95ms agoshowed up right
after a verify ran, because the elapsed helper subtracted a just-written timestamp from a
coarser 1 Hz clock reading and never clamped the result. -
The footer no longer runs its two hint groups together. The view's own hints and the global
tail were joined by a bare space, sou unblock (3) esc backread as one hint whose key was
(3). They are separated by the sameΒ·both groups already use internally. -
Home stops offering to create your first project when you already have several. The
get-started row gated on whether a project was selected rather than whether any exist, so
browsing without a current pick contradicted the card beside it reading "3 projects in storage".
The same card also now says "1 ticket" rather than "1 tickets". -
A blocked task's rejected diff is no longer destroyed on the parallel implement path. The
serial path already quarantined a self-block's rejected diff togit stashso the shared
worktree stayed clean for the next task; the parallel path's per-task worktree had no such
step, so a worktree that ended up blocked was force-removed with its uncommitted diff still in
it β verified, committed-then-unlandable work included, since a fold conflict re-blocks an
already-donetask after its commits landed. Both paths now stash the rejected diff before the
tree is touched again, keyed on sprint + task and located by its own message rather than by a
caller-remembered index, with every push / list / pop in the run serialised through one
in-process queue; a stash pushed by another process mid-run stays out of scope. The parallel
path also keeps the task's worktree branch ref alive instead of deleting it whenever the task
ends blocked or the branch never completed its fold β a Ctrl-C landing between a task settling
doneand its fold used to delete the very ref holding that task's unfolded, already-verified
commits. That holds even when Ctrl-C lands after the block is saved but before the task's chain
has finished: the teardown checks the task's saved state before removing the worktree, and leaves
the worktree on disk when that state can't be read. The kept ref is a recovery window, not permanence: the next launch of that task
force-deletes it. Past that point a blocked task's commit SHA is still intasks.json(an
unblock archives it intoretiredAttempts) and onprogress.md's- Commit:line; an
interrupted fold's SHA survives onprogress.mdonly, because the run's epilogue resets that
task to its pre-wave copy β either one feeds a manualgit cherry-pickuntil gc prunes the
object. -
A crash inside a parallel task's chain no longer strands its worktree. An error thrown
(rather than returned) anywhere in a task's per-task chain was swallowed and replaced by an
unrelatedTypeError, and the worktree teardown was skipped entirely β so the task's
wt-<task>directory and branch ref survived on disk and every later launch of that task failed
while creating its worktree, until someone removed them by hand. The teardown now runs on that
path too, and the original error surfaces unchanged. -
Restoring a quarantined diff can no longer leave conflict markers behind. When the stashed
diff from a blocked attempt could not be re-applied cleanly, git had already written the
conflicted, marker-laden merge into the working tree while the harness logged that the retry
would start from a clean tree and carried on β so the next verify read the markers as a broken
baseline and the following commit could contain them. The diff is now only restored onto a clean
tree, and a restore that fails is undone back to that clean state; the diff stays in the stash,
recoverable under the same message. On a tree that already has changes (kept at the dirty-tree
prompt, say) the diff is left in its stash with a warning naming it, rather than risk an undo that
would wipe those changes too. -
Resuming a parallel implement run no longer silently does nothing. A dependent task whose
prerequisite had already settleddonein an earlier session read as a dangling dependency once
the resumed run narrowed its graph to just the remaining tasks β the schedule failed closed, and
that failure was swallowed into an empty wave list, so the run reportedcompletedhaving run
nothing. Resuming now tells the scheduler which ids outside the queue are already satisfied, and
a task graph that's genuinely unschedulable (a real cycle or dangling id) is reported to the
operator as a launch failure instead of a quiet no-op. -
ralphctl sprint closeon a sprint that isn't inreviewfails immediately with the
invalid-state error, instead of first promptingN task(s) are blocked β¦ Close anyway?for a
close that was never valid β and, in a script, instead of exiting with a confirmation-missing
error that named the wrong problem. -
Model-authored task text can no longer drive the operator's terminal. A
task-blocked
signal's reason, question and "what unblocks me" come off a generator that has just read an
attacker-controllable repository, and a task's name comes off the planner, so all of them are
now stripped of terminal control characters and length-clamped before they reach the CLI, the
Tasks panel or an OS notification β a prompt-injected name or answer can't emit ANSI/OSC escapes
into the terminal or flood a list row with a multi-megabyte field.task list,task unblock,
sprint progressandsprint closeneuter every name they echo. The same normalisation runs
when the signal is read, and it never rejects one: an over-long field is truncated, not refused,
so a single bad field can't sink a whole run. -
A bundled skill can no longer talk a phase β or a turn β into an invalid signal. The
cross-phase iterative-review skill hardcodedtask-blocked, and the TDD and debugging skills
namedtask-completeanddecision, in prose that is also loaded intoplan,ideateand
readinessβ phases whose contract accepts none of them β and, insideimplement, into the
evaluator turn, which is installed with the same file and has no schema for either. One stray
signal fails validation for the wholesignals.json, so a fully approved plan, ideate,
readiness or evaluation session was silently discarded. The iterative-review skill now points
at whichever blocked/note signal the flow it was loaded into actually accepts, and all three
qualifytask-completeanddecisionas generator-role kinds. Skills that suggested writing a
notenow do so only when the active output contract accepts one β the best-of-N judge turn,
which runs with the same skills mounted, accepts only its verdict, and a coachednotethere
silently discarded the judge's choice. A compatibility test now checks
every bundled skill's signal mentions against the contract of every flow and turn it mounts in.
The evaluator-checkpoint and decisions prompt partials now show a real ISO-8601 timestamp
instead of a<ISO-8601 timestamp>placeholder, so a model copying the block verbatim writes a
file that validates. -
Interactive sessions no longer hang on a black screen after the TUI hands over the terminal.
Seen with Grok but provider-agnostic: an interactive CLI queries the terminal for its capabilities
on startup and blocks until the reply arrives, and ralphctl β whose stdin handle was still reading
after Ink unmounted β swallowed that reply about half the time (every time through the production
host). The TUI now releasesprocess.stdinbefore spawning the child and restores it afterwards.
Measured in a real iTerm window through the real host: 0 of 8 launches reached Grok's pager before,
8 of 8 after. Every interactive spawn also drops aspawn-context.jsonbeside the session's other
artifacts recording the stdin state it was handed, so a future hang can be diagnosed from disk.
Full writeup in.claude/docs/INTERACTIVE-HANDOFF-HANG.md. -
A parallel task that hits its attempt budget while resuming now stays blocked, instead of quietly
coming backin_progressand re-blocking (and re-notifying) on every relaunch. The same fix closes a
worse sibling bug: a task that failed or was interrupted mid-wave could reset an unrelated, already
finished task in that same wave back totodo, discarding a completed and folded result. Merging a
wave's results now only ever updates the one task each part of the wave actually settled, and a block
already saved to disk right before an error or an abort is recovered rather than overwritten. -
A relaunched task with quarantined work no longer loses it. Two related fixes: a baseline check
that blocks the very first thing an attempt does no longer restores that quarantined work first and
then leaves it stranded, and a Ctrl-C or crash landing in a parallel run right after that work was
restored β but before it was committed or blocked again β now puts it back where it can be recovered,
instead of removing the task's worktree with it still inside, even when an earlier failed restore had
already left an older, unrelated quarantined entry for that same task sitting in the stash. The
quarantined work also no longer counts toward the baseline check itself, which previously could let it
be committed once the operator chose to proceed past a check it had turned red. -
Relaunching a bugfix task after it's unblocked now continues from the failing test it already wrote,
instead of silently writing and validating a second one on top of the same quarantined work. If the
restored work brought back a change to that test too β a weakened assertion from the attempt that
blocked, say β the test is kept rather than discarded, so the evaluator re-checks it and reports the
tampering instead of the retry looking like it validated a fresh, untouched test; it's dropped only when
the test genuinely isn't in the tree. -
A parallel task's isolated worktree now checks what its setup script changes there against what the
operator already saw in the main checkout, instead of letting it ride along unremarked. A change the
operator already dealt with (kept, stashed, or reset) is discarded from the worktree right after setup β
logged with the paths and a remedy, since a red verify in that worktree can trace back to it β before
the task's commit; a change they never saw blocks the task β or is kept with a warning, under the
"continue" dirty-tree setting β naming the script. The answer is remembered past 200 seen paths too,
collapsing into the directories that cover the most of them rather than losing paths off the end, and it
no longer trusts a stale success: a later run for that repo that actually failed or errored now forces
setup to run again on the next launch instead of skipping it. A sprint started before this shipped runs
setup once more on its next launch either way, to record an answer for the first time. -
A working tree with only new, untracked files is no longer treated as clean. A repository or global
git setting that hides untracked files fromgit status(status.showUntrackedFiles=no) could make
ralphctl's dirty-tree checks, its commit step, and its quarantine stash all miss brand-new files β
silently skipping a commit of the AI's own work. -
A dependent task that's only blocked because it's waiting on another blocked task no longer stays
shown as blocked in the Execute view once that other task is unblocked. It now correctly renders as
runnable again, matching what already happens for a task unblocked directly. -
A task left behind by a sprint reopen that didn't fully complete is reachable again. If unblocking
one task revived it but couldn't finish reopening its closed sprint, that task used to look like
ordinary, un-flaggedtodowork β and a retry that failed the same way a second time still reported
success. Sprint-detail'suand the Sprints list's bulk unblock both now recognize this case, lead with
a warning instead of a success tick while it's still stuck, and spell out the fix: run
ralphctl sprint reopen <id>, reload β sprint-detail gains the samerchord the Sprints list already
had, since this view never polls for changes made outside it β then unblock again. -
A skill folder left behind by a run that was killed or crashed mid-launch no longer permanently
shadows a newer bundled skill. ralphctl now marks every skill folder it installs with the run that
created it, so a later run can tell an abandoned leftover from a project's own copy and refresh it,
instead of treating it as a deliberate override forever.
Full changelog: v0.22.0...HEAD
npm: https://www.npmjs.com/package/ralphctl/v/0.22.0