Skip to content

v0.22.0

Choose a tag to compare

@github-actions github-actions released this 17 Sep 11:08
· 416 commits to main since this release
4598747

What's changed

Added

  • Grok Build CLI (xai-grok) as a fifth backend, joining Claude Code, GitHub Copilot,
    OpenAI Codex, and OpenCode. Install the grok binary, sign in with grok login, then
    ralphctl settings apply-preset grok-only (or pick xai-grok per flow). Catalog models
    are grok-4.6 (flagship) and grok-4.5. Doctor cannot check Grok login (no auth-status
    command). Readiness writes the shared AGENTS.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 no write tool β€” Write and Edit are aliases of search_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, where grok-prompt.md and signals.json live, 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 removes web_search / web_fetch, and any closed gate adds --no-subagents. Grok has
    no --add-dir β€” extra roots stay a named over-grant (--sandbox off is 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_HOME pointed inside the repo would put signals.json under 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 the AGENTS.md and .grok/skills that 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 -s lands.

    One thing an interactive Grok session leaves on disk is worth knowing about: it writes
    grok-debug.log beside the session's other artifacts β€” a stdio: '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-terminal done
    sprint. Lands it back in review (idempotent β€” an already-review sprint passes through
    unchanged) and enforces the same single-active-per-project invariant as sprint activate, so
    a reopen can't collide with a sprint already live on the project. sprint close also gained
    -y/--yes to 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 the Next steps block all now show a blocked count β€” including
    once a sprint is done, since unblocking there reopens it (see Changed) rather than leaving the
    count meaningless. Sprint-detail gets a B chord 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
    at planned/active β€” it now says that every remaining task is blocked and unblocking one
    makes it runnable again. On the CLI, sprint progress groups 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 a ralphctl task unblock <id>
    hint β€” and task list prints a blocked task's reason plus a recovery hint the same way.

  • The generator can say what, specifically, it's stuck on. The task-blocked signal gains
    optional blockerClass (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 both ralphctl task list and 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 and progress.md, which meant an unattended run's
    most common failure mode was also its quietest.

Changed

  • Both doors to done now 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 close prompts with the same names (-y/--yes skips 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 new retiredAttempts list rather than discarded β€” so
    ralphctl runs stats and 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, and runs stats folds 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. Existing tasks.json files load unchanged; nothing
    needs migrating.

  • Unblocking a task on a done sprint 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 reopen does, rather than walking around it: when another sprint of the project is
    already active or in review, the task is still revived but the sprint stays done, and the
    operator is told so: the CLI prints a note naming the peer that holds the project and the
    ralphctl sprint close that releases it, sprint-detail's u appends the same reason to its
    toast, and the Sprints list's bulk u counts 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
    already todo never 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 back implement, implement-continuation, evaluate, evaluate-continuation, and
    reproduce; task-field and task-sizing guidance is likewise shared between plan and ideate
    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 in signals.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 like Array<Change>, Set<Note> or Promise<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_progress with 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
    B jump-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. Pressing b for 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 a review
    sprint reopens it to active. The header card read ACTIVE while the breadcrumb still claimed
    REVIEW.

  • The Baseline card no longer reports a negative age. βœ“ Pre verify -95ms ago showed 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, so u unblock (3) esc back read 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 to git stash so 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-done task 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
    done and 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 in tasks.json (an
    unblock archives it into retiredAttempts) and on progress.md's - Commit: line; an
    interrupted fold's SHA survives on progress.md only, because the run's epilogue resets that
    task to its pre-wave copy β€” either one feeds a manual git cherry-pick until 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
    unrelated TypeError, 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 settled done in 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 reported completed having 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 close on a sprint that isn't in review fails immediately with the
    invalid-state error, instead of first prompting N 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 progress and sprint close neuter 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 hardcoded task-blocked, and the TDD and debugging skills
    named task-complete and decision, in prose that is also loaded into plan, ideate and
    readiness β€” phases whose contract accepts none of them β€” and, inside implement, into the
    evaluator turn, which is installed with the same file and has no schema for either. One stray
    signal fails validation for the whole signals.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
    qualify task-complete and decision as generator-role kinds. Skills that suggested writing a
    note now 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 coached note there
    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 releases process.stdin before 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 a spawn-context.json beside 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 back in_progress and 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 to todo, 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 from git 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-flagged todo work β€” and a retry that failed the same way a second time still reported
    success. Sprint-detail's u and 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 same r chord 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