Gentle AI v3.4.0 is a minor release that closes the loop between work-unit commits and native review, moves pi's reviewer roles fully into host-mediated territory, bounds reviewer context before review authority is ever created, and retires the RTK Community Tool integration — the release's one breaking change. It also ships six fixes: an OpenCode V1 lens-capture relay, a telemetry scrape-size ceiling that had been silently zeroing the runtime dashboard and the public open-data feed, unbounded dedup-table growth in the telemetry collector, an OpenCode agent that configured itself when it was never selected, a native Claude discovery test pinned to the real CLI reporting floor, and a Windows Full Suite that had been red since v3.3.0. The provider contract stays byte-frozen at 1.2.0; the review-integration contract itself advanced additively — capabilities schema gentle-ai.review-integration.capabilities/v2.6, status schemas v8 and v9 added, and the assess schema extended — so no existing consumer breaks.
Provenance
- Previous stable:
v3.3.0→e28af0fd7f8a11b5ee1089b3e13465a500590c41 - Release target:
v3.4.0→82a6de96ca6e1cb4f6bf603fe0c08ef1c2039833 - Release workflow: run 35438011090
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.2.0
What's new
review assess names the exact next move
After every work-unit commit, gentle-ai review assess now reports candidate.consumed, review_due, and a specific review_due_reason — high_risk, slice_budget_reached, passive, under_budget, or already_reviewed. When a review is due, it also returns next_transition with the exact review status --next-transition invocation for the same --base-ref/--committed-only selectors (plus an optional --agent). The installed Organic Driven Development routing guidance now runs that returned command verbatim after each work-unit commit instead of reconstructing the rule from prose, so a due review is no longer something an orchestrator can silently skip. The change is additive on gentle-ai.review-assessment/v1.
Included work: #4784 (issues #4611 and #4783).
Pi reviewer roles are host-mediated
The refuter and targeted-validator roles on the pi runtime used to be spawned by Go itself as pi --print --no-extensions, which could not see providers registered by pi extensions (Model not found) and stripped env-provided API keys. review status now renders pi's capture-refuter and capture-validation collect inputs as --materialize=true plus a submission descriptor, the same shape lenses already use; gentle-pi materializes the request, runs the model in-process through its own live model registry, and submits the result through the new --input=<path|-> form, admitted through Go's existing raw admitters. --execute now refuses typed for host-relay runtimes, and the Go-owned pi adapter and its ~/.pi/gentle-ai/models.json routing are deleted. The negotiated status schema advances to gentle-ai.review-integration.status/v9 to carry the new submission descriptor (v5 forbade submission on role inputs).
Included work: #4784 (issues #4611 and #4783).
Reviewer context is bounded before authority exists
START previously checked a candidate only against the 4 MiB Git ceiling, while a runtime reviewer holds far less than that — so an oversized candidate could freeze review authority and then fail every capture with Prompt is too long, with no way out once authority existed. START now proves, before persisting anything, that the candidate's frozen evidence fits a 200 KiB per-runtime budget for every role, not only the lens; generated paths travel as metadata summaries instead of full content. The correction stage, which cannot be bounded the same way because findings and corrections are free text, gets a typed stop instead: correction_context_budget_exceeded, with review abandon named as its exit from any non-terminal state. Two narrower gaps stay open and tracked as follow-ups: review capture-result --input does not yet consult the budget guard (#4777), and review invalidate rebuilds current-snapshot evidence rather than detecting drift (#4778) — both matter specifically for review recover, which mints successor authority without passing through the START guard.
Included work: #4755 (issue #4680).
Breaking changes
- RTK integration retired. #4766 removes the RTK Community Tool from gentle-ai's active product surface: its source, acquisition, runtime, status detection, install/backup/persisted-restore/sync branches, TUI installation and selection paths, and all RTK-specific docs are gone. The generic Community Tools framework and CodeGraph behavior are untouched. This is a repository-only change — user-owned RTK binaries and configuration on disk are not removed or modified. Two behavior changes follow from the removal: existing presets no longer select community tools by default, and an unsupported RTK selection now reports the tool as unavailable instead of attempting to use it. This is the declared breaking change of v3.4.0.
The module path stays at /v3, and the provider contract remains byte-frozen at 1.2.0. No review CLI flag was removed or changed meaning; review assess and review status gained fields and a schema version additively.
Run gentle-ai sync after upgrading: the installed orchestrator guidance (the post-commit review rule that now follows review_due/next_transition) and the OpenCode/pi managed assets both changed in this release.
Upgrade now
brew upgrade gentle-ai
gentle-ai syncWindows and other source installs:
go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@v3.4.0
gentle-ai syncRun gentle-ai sync after upgrading so managed agent, reviewer, and runtime assets match the installed binary. Claude Code, OpenCode, and pi users in particular need the sync to pick up the new post-commit review_due routing and the pi host-mediated role rendering.
What was fixed
OpenCode lens capture is relayed from a provider-owned task
The OpenCode V1 RDD review path required the model itself to assemble the GENTLE_AI_REVIEW_BINDING JSON before a lens capture could run. Go now emits an exact, opaque provider_task for OpenCode lens captures through status schema v8 and capabilities v2.6; the orchestration and cross-lane paths relay that task unchanged instead of reconstructing it, while legacy admission stays compatible and OpenCode V2 continues to fail closed.
Included work: #4765 (issue #3343).
Telemetry collector: VictoriaMetrics scrape size cap
On 2026-09-18 the collector's /metrics exposition crossed the 16 MiB VictoriaMetrics default in production: every scrape was refused, the runtime dashboard panels and the public open-data window read 0, while the collector kept accepting deliveries underneath. The VictoriaMetrics unit now ships -promscrape.maxScrapeSize=64MiB, and the docs record the failure signature and diagnosis commands.
Included work: #4770 (issue #4769).
Telemetry collector: dedup retention and daily compaction
The runtime_delivery_ids table, whose only job is momentary replay rejection, was growing by roughly a million rows a day toward a 100M-row table with no retention of its own. It now gets its own retention (--runtime-dedup-days, default 2, refused below 1, clamped to --retention-days), purged in 50,000-row batches inside short transactions. After each daily maintenance run the collector checkpoints its WAL passively, truncates it when no outside reader has it pinned, and runs a bounded VACUUM only when at least 25% of a sufficiently large file is free and the live data fits in 512 MiB; a larger rewrite is reported as vacuum_deferred for an offline vacuum instead of holding the single writer online for minutes.
Included work: #4774 (issue #4773).
Gentle Logo no longer configures an unselected OpenCode agent
ComponentOpenCodeGentleLogo installed its plugin, wrote configuration files, and registered managed backup paths even when OpenCode was not among the selected agents — for example, running gentle-ai sync --agents claude-code still touched OpenCode state. The component's apply and sync steps, and its path registration, are now guarded on OpenCode actually being selected.
Included work: #4780 (issue #1212).
Native Claude discovery test gated on the real CLI reporting floor
The native claude mcp list discovery test assumed uniform reporting behavior, but piped output only reports unapproved project .mcp.json servers as "Pending approval" starting at Claude Code CLI v2.1.154. The test now parses claude --version first and skips with a named reason below that floor, at an unparseable version, or when the CLI is unavailable, instead of asserting against a contract the installed CLI does not implement.
Included work: #4157 (issue #3969).
Windows Full Suite restored, test-only
The Windows Full Suite had been red on main since v3.3.0 (e28af0fd), from two unrelated test defects. Node's os.homedir() reads only USERPROFILE on Windows, but the OpenCode V2 catalog harness redirected only HOME, so the plugin wrote its cache under the runner's real profile and the harness's readdir hit ENOENT; the harness now sets USERPROFILE too. Separately, three review assess tests built their expected next_transition.command from raw --cwd=<repo> tokens while production shell-quotes any token containing unsafe bytes, so Windows paths with backslashes mismatched; the expectations now go through the same shell-quoting helper as production. Both fixes are test-only; no production behavior changed.
Included work: #4789 (issue #4788).
Numbers
35 non-merge commits, 9 merged pull requests, and 5 unique GitHub PR authors since v3.3.0.
Install
brew install Gentleman-Programming/tap/gentle-aior
go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@v3.4.0Windows remains supported through the Go installation path. Official Windows binary archives and Scoop publication remain unavailable; Windows upgrades fail closed to Go-based guidance rather than downloading unsigned binaries.
Signed platform archives below: linux_amd64, linux_arm64, darwin_amd64, darwin_arm64, with checksums.txt and its minisign signature.
Full changelog: v3.3.0...v3.4.0