gentle-pi v4.8.0 — Design Canvas, Gentle Desktop RPC and Gentle AI v4.5.0

Gentle Shell v4.8.0 is a feature release. It pins Gentle AI v4.5.0, moves the bundled Engram core to 3.7.2 with the gentle-engram 0.8.0 companion, and adds a design canvas that turns artboards into implementable, reviewable parts — with layout arrangements, a minimap, a token inspector, accessibility checks, PNG/PDF/HTML export and a Spanish or English interface. A new structured RPC channel lets Gentle Desktop read configuration, switch permission modes, watch subscription usage, control background jobs and subagents, and open the canvas without ever writing into the conversation. Reviews got cheaper and more honest: a native review runs inside one parent call, and a review that stops at correction_required or escalated can return the findings it admitted as non-blocking. Agents gain a load-time tool overlay, parallel writers launched together, and a capped child report; a commit that would add unresolved conflict markers is refused, and git push grants are remembered by operation variant. NaN ships four new models, the package tracks Pi 1.5.2, and full-delegation orchestration drops 20% of its measured cost. Four community authors contributed to this release. The npm package remains gentle-pi.

Provenance

• Previous stable: v4.7.0 → 8e11f0e2fb19af2a28233d1774848f7a3a33bbf1
• Release target: v4.8.0 → 3dc9029755912358d0a172b4972e5842c239570c
• Release validation: run 43547130441 passed package verification, published gentle-pi@4.8.0 to npm with provenance, built, verified and attached the installers, and verified the bundled distribution 4.8.0-1.5.2 on macOS, Windows and Linux before attaching it. The distribution job was rerun once because the npm registry had not yet served the just-published version after its 10 attempts.
• Pinned Gentle AI: v4.5.0 (f2f7d7b); the review provider contract moves additively from 1.4.0 to 1.5.0, and the negotiated capability identity is unchanged.

What's new

Gentle AI v4.5.0, Engram 3.7.2 and gentle-engram 0.8.0

The bundled runtime moves from Gentle AI v4.4.0 to v4.5.0, which returns the non-blocking findings of a stopped review to a client that opts in, qualifies Windows 10 22H2 for the Separate installer, delivers the core-plus-on-demand module split to Codex, and moves the provider contract to 1.5.0 with one additive stop reason, correction_request_unavailable.

The bundled Engram core moves from 3.5.2 in v4.7.0 to 3.7.2: first to 3.7.0 with the daemon change below, then to 3.7.2, the packaging-only core release that carries the gentle-engram 0.8.0 companion. See Pinned runtime.

Included work: #3253 (issue #3251).

The design canvas turns artboards into work

The canvas now has a server and data layer of its own: design/<slug>/layout.json holds artboard positions and arrangements, parts.json records what was handed to the session, comment edits and replies are stored next to the design, and the token inspector reads design/system.md read-only without ever throwing on a missing or malformed file. A tool rail with configurable single-key shortcuts drives the canvas, artboards move and arrange, and a minimap tracks the board and the viewport. One preview size selector, 8/48 focus margins and a Desktop frame that fills the window replace the old control; All sizes frames render every registered size with an overflow chip, and a comment remembers the size it was made at.

Each artboard's ⋯ menu exports the board as PNG, PDF or HTML. Implement this can now send only one part of an artboard, list the parts still partially implemented, and remove a part that was already sent. A Technical details toggle opens a token inspector that names the matching design system token for each value, and a Quality tab runs five accessibility checks inside the artboard's own frame — contrast against WCAG AA, target size at 24×24, missing alt, unlabeled form fields and skipped headings — with Show and Ask the agent to fix.

The canvas interface speaks Spanish or English, chosen in Settings › Language (with Match the browser), covering the shell, layout, minimap, preview sizes, export, Compare, comments, handoffs, parts, the token panel and translated findings, with coverage tests. English reads exactly as before.

Included work: #3128 by @doblas, #3145 by @doblas, #3146 by @doblas, #3148 by @doblas, #3153 by @doblas, #3177 by @doblas, #3196 by @doblas, #3197 by @doblas, #3198 by @doblas, #3236 by @doblas, #3237 by @doblas, #3238 by @doblas.

Gentle Desktop controls the session over RPC

gentle-shell.desktop-rpc/v1 is a structured control channel built only on Pi's public extension API. Desktop sends /gentle:desktop <json> as an ordinary RPC prompt; responses and events come back as JSON through the gentle-desktop-rpc widget channel, correlated by requestId, with a monotonic event seq and get_snapshot recovery, and control traffic never enters the conversation history. It exposes capabilities and snapshots, permission mode, six configuration stores with revision-checked writes, subscription usage and refresh, the design canvas, background jobs and subagents with per-helper model, tokens and cost. Desktop can also apply a saved profile through Shell's own apply path, so no second implementation exists; when the profiles screen would ask for confirmation, nothing is written, and the response carries the same prompt plus a content-bound token that asks again after any change. The channel is active only in RPC mode with GENTLE_SHELL_INTERACTIVE_HOST=1, is never an agent-callable tool, and keeps credentials, raw provider errors, prompts and tool output off the wire; job commands and unconfirmed modes stay off it.

Included work: #3240 by @decode2, #3241 by @decode2, #3252 by @decode2.

Reviews report what stopped them, and one call runs the review

A native review used to cost the parent 9 to 11 tool calls because every provider transition went back through the model. gentle_review_run now follows those transitions inside one parent call, is registered by default while RDD is not off (opt out with GENTLE_PI_EXPERIMENTAL_REVIEW_COORDINATOR=0), never appears in subagent sessions, records reviewer-run forecasts instead of stopping on them when no UI is present, and returns the provider closure's advisory_findings.

A review that stops at correction_required or escalated can also return the informational, follow-up and refuted findings it admitted: STATUS accepts an opt-in --non-blocking-findings request while negotiating the v2 review contract, the field is declared optional and bounded, the option is scoped to review runs rather than ordinary calls, and provider-owned review-due boundaries are preserved. Direct native calls, consent and closure authority are unchanged.

Included work: #3134, #3135, #3136, #3174, #3211, #3212, #3213, #3214, #3215, #3219, #3221.

Agents get tool overlays, parallel writers and a smaller context

Subagent tools now have a load-time overlay layer that mirrors model routing: extension drop-ins, then global, then project precedence, adding or removing tools per agent without editing the package-owned agent file — the hand-edit that dropped the managed-assets.json entry and froze the agent out of upgrades. Overlay notices are surfaced through list_agents, and a forced refresh keeps ownership while replacing an outdated body.

Two writers launched together are admitted in organic mode instead of colliding on one admission, and a child's report delivered into the parent's context is capped. The always-on prompt keeps shrinking: six rarely used tools leave the per-turn declarations when Code Mode can reach them, the effective skills block lists only what Pi did not list, reply-language anchors and the todo reminder stay append-only across requests, and full-delegation no longer reads the task docs into the orchestrator's context to derive its edit surfaces. Measured on the F4 full-delegation benchmark over three repetitions, that last change cut parent cost from $0.750 to $0.513 and total cost by 20% with flat wall time and no quality regression under a blind review.

Included work: #3223, #3110, #3115, #3244, #3093, #3096, #3100, #3103, #3106, #3111.

The bundled Engram runs as a daemon

The bundled core moved to 3.7.0, the first release with the daemon verbs, so a shared server started by Shell is now launched as engram run -d and waits for the same /compatibility ready contract Shell already required of a reused server — which makes it visible to engram ps, stop, logs and restart. A core older than 3.7.0, or a failed or timed-out handoff, keeps the legacy detached serve, so the change degrades instead of breaking. The companion gate compares gentle-engram's declared runtime-contract digest with the digest the pinned core answers, and only warns. This release moves the core pin again to 3.7.2; see Pinned runtime.

Included work: #3118 (issue #2346) by @decode2, #3121 (issues #3122, #3123) by @decode2.

NaN models, Pi 1.5.2 and a package check that runs anywhere

The NaN catalog adds kimi-k3.1-pro, qwen3.8-max, deepseek-v4-pro and hy4 (1M context, conservative 32,768 output cap), follows the documented per-model reasoning_effort contract, and labels Alt+U rows as a per-model token quota instead of a credit balance that an API key cannot read. Chat output caps now match the published contract. The package moves to Pi 1.5.2 with a standing release-age exemption for @earendil-works/* while minimumReleaseAge: 4320 stays for everything else. The package check loads with plain node on every supported version.

Included work: #3091, #3160 (issue #3158) by @decode2, #3164, #3088 by @doblas.

What was fixed

A review keeps its intent, its range and its delivery

Assessing a committed range no longer mixes in untracked files that were never selected, while an intended-untracked selection still reaches the committed candidates; reminders stay on the explicitly assessed range, empty selection defaults are ignored, and a delivery directory survives output redirections. Public consent copies carry the Pi binding, shell delivery keeps its scheduling and routing context, and stalled reviewer streams are bounded with progress reported instead of hanging. Code Mode guidance now explains direct-only tools, and an unsupported severity classification says why it is unsupported. An explicitly requested verification after quota recovery is permitted again.

Included work: #3005 by @dnlrsls, #3043 by @dnlrsls, #3170 (issue #3169) by @Yoryoboy, #3172 by @dnlrsls, #3178 by @dnlrsls, #3191 by @dnlrsls, #3192 by @dnlrsls, #3194 by @dnlrsls, #3167 by @dnlrsls, #3183 by @dnlrsls, #3184 by @dnlrsls, #3175 by @dnlrsls.

Agents stop losing work between turns

A late answer to a child query used to be dropped; it is now delivered. Provably dead peers are purged from orchestrator_list, JSON-string orchestrator state is accepted with an actionable error, and presence discovery pages through busy directories so published state is never lost. Job notices survive session switches, a recorded agent body hash is never dropped when the history is regenerated, the current verifier body is registered, and a writer admission rejection names the invalid entry instead of refusing anonymously.

Included work: #3107, #3186 (issue #1443) by @decode2, #3189 (issue #3188) by @decode2, #3190 (issue #3185) by @decode2, #3209 by @decode2, #3162, #3171 by @dnlrsls, #3114.

Verification and ODD tracking report what actually happened

A verifier-caused setup error is self-corrected without a human round trip, verification follows the change kind instead of re-running the writer's suite, a user's failing command runs even when it is that suite, and a reported failure counts as reproduced only when the baseline shows it. Custom reconciliation gates no longer stop ODD tracking, an approved text verdict that no earlier change carried is applied, and ODD/review friction that only cost turns was removed. A custom wake no longer resets the todo freshness clock, a scratch archive failure propagates instead of disappearing, isolated preparation preserves Git semantics, and session consent persistence is diagnosed and fenced.

Included work: #3084, #3101, #3126, #3155, #3083, #3112, #3002 by @dnlrsls, #3187 by @dnlrsls, #3017 by @dnlrsls, #3018 by @dnlrsls, #3019 by @dnlrsls, #3047 by @dnlrsls.

A commit cannot carry conflict markers, and pushes remember their grant

A hand-resolved merge once reached CI with conflict markers still in the file. The primary session's bash hook now refuses a git commit that would add an unresolved conflict and names each path:line; it understands git add … && git commit, and during a merge, cherry-pick or rebase it counts a marker only when the added content has both sides. Allow for this session and Always allow git push now remember the git push operation plus its option variant (plain, --delete, --mirror, force) instead of the exact command, so pushing different branches no longer re-prompts, while force variants stay separate and -f/--force/--force-with-lease remain hard-blocked.

Included work: #3113, #3242.

Prompts, skills and the registry stop contradicting themselves

An explicit user request now wins over the handoff's RDD rule, the always-on prompt no longer carries contradictory instructions, and two blocks left the every-turn surface. The lazy orchestrator modules and the skill/tool guidance resolve the contradictions they shipped with, the skill registry shares one disk-only view while runtime skills stay session-local, a late watcher refresh no longer notifies through a stale session context, and idle fallback scans and multi-process registry thrash are bounded and covered. The rdd-defect-workflow trigger is narrower and the unread review ledger contract is gone.

Included work: #3168, #3108, #3102, #3099, #3089 (issue #3020), #3127 (issues #2580, #3072), #3166 by @dnlrsls, #3129, #3125.

Updates, the canvas surface and the shell chrome

A managed Pi self-update now installs the latest stable Pi immediately, and Pi packages co-published with an exact version are exempt from the strict release-age wait, so a fresh Pi is not refused. The design canvas refits the overview when the window settles, a canvas watcher registration failure is surfaced instead of lost, and the working wave is driven by elapsed time instead of render count.

Included work: #3080, #3081, #2793 by @doblas, #3159 (issue #3156) by @decode2, #3157 (issue #2643) by @decode2.

Pinned runtime

The pinned Gentle AI runtime moves to github.com/gentleman-programming/gentle-ai/v4 v4.5.0 (tag commit f2f7d7b16c2cf1afe5e07f717cf8265946ac3feb): signed release archives on Darwin and Linux, pinned by archive and extracted-binary SHA-256, and a SumDB-verified source build on Windows (h1:81Hsy+cboAbUse1ORVJuwji6V9sRIGlFwC73EtMdw0c=). The review provider contract moves from 1.4.0 to 1.5.0 with the additive correction_request_unavailable stop reason; the binary still advertises gentle-ai.review-integration.capabilities/v2.6, so no capabilities/vN identity was added, and the new 4.5.0 NATIVE_CLI_CONTRACTS row repeats the 4.4.0 row. The bundled Engram core is pinned at 3.7.2, and the gentle-engram companion stays the unversioned npm:gentle-engram source that resolves npm latest; Shell warns, without blocking, when the companion's runtime contract differs from the pinned core's.

Breaking changes

None. Existing ODD, SDD, review, and package interfaces remain compatible.

Upgrade

pi install npm:gentle-pi@4.8.0

Restart Pi, then run gentle-ai sync so the managed orchestrator assets match the pinned runtime. Bundled installs run gentle-shell upgrade. The Engram store keeps the same schema, so no store migration is required, and Pi peer support is unchanged (>=1.2.0).

Numbers

261 non-merge commits, 111 merged pull requests, and 5 unique GitHub PR authors since v4.7.0.

Thanks to the community authors of this release: @decode2, @doblas, @dnlrsls and @Yoryoboy.

Verification

• Local suite (node scripts/run-test-suite.mjs, macOS arm64, Node 24, clean environment) on the head of #3253: 10669 tests, 10574 pass, 94 skipped, 1 fail. The failure is the timing-sensitive gentle-agents job-notice load test; it passes 3 of 3 runs on its own and on the pre-release baseline. The provider-contract and runtime-harness stages pass.
• Pin bump #3253: focused suites 433 pass, 0 fail, 8 skipped; node scripts/test-packed-runner.mjs against the published release assets reports packed package E2E passed (gentle-pi 4.8.0; Gentle AI 4.5.0); type checking reports no diagnostics.
• Package verification: 288 package resource files and 69 exact byte-pinned contract artifacts for the v4.5.0 runtime; npm pack --dry-run lists 1271 files (13.0 MB packed, 29.4 MB unpacked).
• Engram pair: the published gentle-engram 0.8.0 companion declares the same runtime-contract digest that the released 3.7.2 core serves on GET /runtime-contract.
• Installers and distribution: the four installer assets are public; the three installer archives match the published gentle-shell-installers-SHA256SUMS.txt and each bundles gentle-pi 4.8.0. The distribution manifest reads id 4.8.0-1.5.2 (Shell 4.8.0, Pi 1.5.2), and its lockfile SHA-256 matches the published lockfile.

Install

pi install npm:gentle-pi@4.8.0

Package: https://www.npmjs.com/package/gentle-pi

Full changelog: v4.7.0...v4.8.0