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 [email protected] 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-delegat...

Gentle Shell v4.7.0 is a feature release. It pins Gentle AI v4.4.0; profiles can choose an orchestrator workflow mode, organic or full delegation, that changes on the next turn; the fullscreen chrome gains header placements, a transparent surface by default, card-style rail sections and mouse controls in every modal; guarded commands can be allowed once, for the session or always; and sessions publish a universal agent-status file any terminal tool can read. Reviews gain an opt-in coordinator, frozen request intent, reviewer execution evidence and actionable blocker diagnoses. Execution got tighter: delegation can no longer escape to an external pane, the sensitive-path guard now covers shell commands, and qualifying child agents get the background job tools they declare. Windows session transport re-arms once after a failed start, pi.cmd shims launch without a shell, and a read-only STATUS that times out on the host offers a rerun instead of a dead end. Twenty-three community authors contributed to this release. The npm package remains gentle-pi.

Provenance

• Previous stable: v4.6.0 → 1f74e9e24473e7e121a96b1680444ae0196d3009
• Release target: v4.7.0 → 8e11f0e2fb19af2a28233d1774848f7a3a33bbf1
• Release validation: run 42401297004 passed package verification, published [email protected] to npm with provenance, and built, verified and attached the installers.
• Pinned Gentle AI: v4.4.0 (55240af); the review provider contract remains unchanged at 1.4.0, and the negotiated capability identity is unchanged.

What's new

Gentle AI v4.4.0 pin

The bundled runtime moves from Gentle AI v4.3.1 to v4.4.0, which brings Antigravity 1.4 parity, faster gentle-shell/gs launches, gs on Windows, and safer Windows restores. See Pinned runtime.

Included work: #3000 (issue #2999).

Profiles choose who writes

A profile now carries an orchestrator workflow mode. organic lets the orchestrator implement inline and delegate when a delegation trigger fires; full-delegation never implements and sends every authorized change to a bounded writer with its code, tests and docs together, while the orchestrator keeps authorizing, routing, deciding, asking, tracking, committing, verifying and reporting. Neither mode is presented as the better one. In /gentle:profiles, w toggles the mode as a draft that is saved with the routing, and the Orchestrator row reads ◎ organic or ⇄ full delegation. The rules follow the active profile on the next turn in both directions, with no restart. The mode is stored under a separate workflow key in profiles.json, so profiles that stay organic serialize exactly as before, and every degraded case falls back to the organic rules.

In full delegation mode the organic routing rules are removed from the orchestrator's context rather than annotated, which shrinks the always-on core from 9,146 B to 5,611 B. Writer admission follows the same mode, so a small task no longer deadlocks between a prompt that forbids inline edits and a runtime that refused a generic writer; the edit-surface guard still runs first. The reply language also stays with the human after an English subagent result.

Included work: #2976, #2987.

Header placements, a transparent surface and card-style rail

Header › top draws the whole header row (model and effort, context, cost, usage) above the conversation, and the previous IDE chrome stays available as Header › split. Every placement at 140 columns or more now uses one bar design: branch, permission mode with its icon (🔥 YOLO, 💥 SUPER-YOLO), model and effort with the agent profile beside it, context, cost and usage, with the titled-rule editor under it. Layout › Surface offers tinted or transparent; transparent is now the default, so a terminal background image shows through the rail, bars and /gentle:panel, and rail sections draw as cards in the active card style. Minimal cards are the default, float cards stay apart in every density, a click anywhere on a card's title row folds its section, and titles take the hover color. The Todos header shows its collapse key, Stats opens with the profile, and the mobile chrome is aligned with the full-width layout.

Fullscreen Customize, Commands and Jobs now accept the mouse, and every actionable control and question label shares one orange hover; hovering never selects, applies, answers or stops anything. Every installation also shows the end-of-run TPS notification by default, with input, output, cache and total tokens and the elapsed time.

Included work: #2896 (issue #2890), #2897, #2904, #2908, #2876 (issue #2875), #2918 (issue #2916).

Scoped command confirmations and RDD controls

A guarded command in Normal mode now offers Allow once, Allow for this session (the exact command), Always allow (saved in the user-level guardrails config) and Deny. Recognized data-loss commands never offer Always allow, hosts without a select dialog keep the plain yes/no confirm, and a malformed guardrails config is refused instead of rewritten. /gentle:rdd and a Customize entry switch RDD through one native mode owner with explicit repository or machine-wide choices, the existing normal, auto, YOLO and super-YOLO session modes are offered from the same place, and native assessment-only work is skipped when RDD is freshly validated off.

Included work: #2931 (issue #2929), #2902.

A universal agent-status file

Interactive top-level sessions publish their status as one documented JSON file per session (gentle-shell.agent-status/v1: agent, session, pid, cwd, working/blocked/idle state, task title and update time) under <config home>/agent-status/, so Herdr or any other terminal tool can show it without a socket. The file is replaced atomically, refreshed at least every 10 seconds, removed on shutdown, and stale records left by a crash are swept at the next session start. Layout › Task summary: on / off in /gentle:customize hides or shows task titles in both this file and the Herdr summary.

Included work: #2949 by @MarsSall, #2947 by @MarsSall, #2958 (issue #2392).

Review: request intent, an opt-in coordinator and clearer blockers

A fresh ordinary START accepts an explicit request file and keeps that intent through native preflight, untracked selection and consent, when the runtime advertises the capability; .envrc and .netrc join the shared sensitive-path policy. A default-off gentle_review_run coordinator follows native transition offers through the existing facade and stops for authored input, a native stop, a failure or maintenance that needs authorization. Reviewer execution facts (effective model and provider, phase, durations, and SDK-reported usage and cost) now survive through relay, facade and coordinator results; a blocked step names its category, actor and next step; optional host relay phase timings can be observed; and an empty candidate range after acknowledgement explains how to ask for the committed range instead.

Included work: #2883 by @dnlrsls, #2884 by @dnlrsls, #2966 by @dnlrsls, #2973 by @dnlrsls, #2975 by @dnlrsls, #2982 by @dnlrsls.

Updates follow the latest Pi and its companions

The managed Pi self-update now selects the latest stable Pi, a Shell upgrade keeps a newer Pi in place, and global installer actions resolve an exact validated latest-stable Pi while frozen release distributions keep their pins. The managed gentle-engram registration no longer carries an exact version ceiling, so Pi's own startup update notice and update --extensions reach it; Gentle Shell installs gentle-engram from npm latest (gentle-engram 0.7.0 (npm latest), paired with engram v3.7.0).

Included work: #2892 (issue #2891).

Pasted images on disk, on request

GENTLE_PI_IMAGES_DISK_CACHE=session writes each pasted image chip to ${XDG_CACHE_HOME:-~/.cache}/gentle-shell/images/<session>/ (directory 0700, files 0600), so local vision models, OCR and other tools have a real path to read. /gentle:images lists the paths for chips the draft still references, the submitted payload stays base64, the session directory is removed on shutdown, and the cache is off by default.

Included work: #2889 by @ipproy...

Gentle Shell v4.6.0 is a feature release. The fullscreen shell becomes an IDE inside the terminal, with a title row, a collapsible rail, a status bar and a framed editor, plus a Panel sheet for narrow screens and Light, Neutral and Power user presets; agents fall back along per-agent model chains when a model runs out; sessions remember the profile they started with; shortcuts can be rebound and /gentle:guide tours the screen; and engaged users can star the project right from the terminal. Bundled installs move to Pi 1.5.0, and scrolling a long fullscreen conversation no longer freezes the shell. The npm package remains gentle-pi, and the bundled Gentle AI runtime remains v4.3.1.

Provenance

• Previous stable: v4.5.1 → e8b2814934f98ded9199f49bde8f482c97eece3a
• Release target: v4.6.0 → 1f74e9e24473e7e121a96b1680444ae0196d3009
• Release validation: run 41902568883 passed package verification, published [email protected] to npm with provenance, built, verified and attached the installers, and verified the bundled distribution 4.6.0-1.5.0 on Ubuntu, Windows and macOS 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.3.1 (2dba778); the review provider contract remains unchanged at 1.4.0, and the negotiated capability identity is unchanged.

What's new

An IDE inside the terminal

Fullscreen Gentle Shell now reads top to bottom as a title row (project name and path on the left, session and profile on the right, the path trimmed first when space runs out), a single tinted rail, a status bar and the editor. The rail holds collapsible ▾ NAME … count sections in a fixed order (Todos, Jobs, Agents, Changes, Review, Integrations) with a ctrl+shift+t todos · alt+u usage · / commands hint line; a click on a header folds it. The status bar carries the branch and dirty count, the permission mode, model and effort, the context gauge, the cost and a usage button that opens /gentle:usage. The editor sits under a ─ ✿ <state> ─ rule with a frameless › prompt, and subagent questions surface above the input as ? explore asked: … /gentle:agents.

Below 140 columns, or with the status bar at the bottom, the rail gives way to one live-work row inside the editor (◐ 3 agents · ? 1 waiting · ✗ 1 … 2/6 todos) and a [ Panel ] button on the editor rule. /gentle:panel (or that button) opens the rail's sections as a full-width sheet at any width: ↑/↓, j/k or the wheel move, and esc, q or a click on esc back close it. /gentle:customize offers three presets, Light (no rail, status at the bottom, minimal density), Neutral (the default) and Power user (adds a Stats section), cycled with alt+l; GENTLE_PI_SHELL_PRESET_KEY remaps the shortcut or turns it off, and the menu marks the preset your settings match. Clickable agent rows share the shell's hover treatment, the Integrations section shows the effective Agent profile:, and light themes paint the frame on a paper background (in Ghostty, set window-padding-color = extend). Every capability of the previous shell is kept; dark themes, RPC hosts and the regular one-line bar keep their previous output.

Included work: #2791 (issue #2773), #2850, #2841, #2752 (issue #2751).

Model fallback chains

Each agent can carry an ordered fallback chain of up to eight provider/model ids. In /gentle:profiles, f on an agent row (or on set every agent) opens its chain: f adds a model from the catalog, e sets that step's effort, shift+↑/↓ reorders, x removes and esc goes back; every change is saved at once on saved profiles, and the row reads ↪ first-model +N. Chains live in profile-fallbacks.json next to profiles.json.

Quota and auth errors move to the next model at once; rate limits, unavailable providers, timeouts and network errors move only after Pi's own retries; context-length, invalid-request, unknown errors and aborts never do. A subagent switches with set_model and keeps its conversation; the orchestrator switches once its run settles and a follow-up message resumes the work, walking the chain once per episode. A failed model is skipped for 30 minutes after a limit or auth error and for 2 minutes after a transient one, a full usage window in /gentle:usage skips it until the reset, and Codex's main usage limit holds back the whole provider. A warning names the agent, the reason and the new model (with 2.0x the price when it costs more), and the agent's sidebar row reads ↪ <task> · <model>. Only chained models are used; an exhausted chain fails the run as before.

Included work: #2801 (issue #2794), #2803 (issue #2802).

Sessions keep the profile they started with

A session's profile now survives resuming in another process, and /gentle:profiles opens on the tab the session launches with, marked ◉ (★ stays the default and ⌂ this repository). /gentle:profiles clear returns new launches to the profile the session started with and leaves the live orchestrator unchanged; on a session already there it says so and changes nothing. A session record that is unreadable or written by a newer version is named with its file, entry and line, and launches stay blocked until a profile is chosen or the session is cleared. When the launch profile no longer exists in profiles.json, a ⚠ notice says its launches keep that routing. The action buttons show their keys, [ u · Use in this session ], [ d · Make default ] and [ s · Save ], shortened on narrow screens.

t in /gentle:profiles stores Standard or Fast for each compatible OpenAI or Codex route, All Fast edits the draft until you save or apply it, and the status bar shows Fast or Standard next to the effort; Fast uses more quota. /gentle:customize now shows one line per setting with its options inline, and Enter explicitly applies preview-first, permission, privacy and audio options.

Included work: #1990, #1991, #1992, #1993 (issue #2456), #2819, #2820, #2821, #2822, #2823, #2853, #2604 (issue #2451), #2689, #2813 (issue #2810), #2816, #2640.

Your own shortcuts and a guided tour

/gentle:customize → Keymaps rebinds the shell's shortcuts: Enter waits for the new key, ⌫ disables the action, r restores its default, and the last row reloads; in the command palette, tab binds a key to the highlighted command. Bindings use ctrl or alt (with or without shift) or f1–f12, keys Pi reserves are refused with the action that owns them, and a key already in use asks first. They are saved in keymaps.json in the Gentle config home and apply after /reload; a GENTLE_PI_*_KEY variable still wins, and an unreadable file falls back to the defaults with one warning and is never overwritten.

/gentle:guide tours the screen with popovers placed next to the part they describe and a step counter, showing only the steps for features that are present. With a model, the agent drives the tour and explains each step; without one, or with /gentle:guide local, →, Enter or Space advance, ← goes back and Esc ends it. /gentle:guide stop closes it, and the startup banner mentions the command.

Included work: #2839 (issue #2838).

Star Gentle Shell from the terminal

After more than five prompts, once the agent has finished and the keyboard has been idle for 30 seconds, a one-line offer appears below the editor in the theme's success green with a right-aligned [star] button. Ctrl+G or a click on [star] stars gentle-shell and gentle-ai through your own gh, thanks you and never asks again; when gh cannot star, both repositories open in the browser instead. Alt+D never asks again, and an unanswered offer hides after five minutes until the next session. The row keeps the longest wording that fits, down to Ctrl+G star, so no word is ever cut. Users whose gh account already starred both repositories are never asked, and the offer stays silent when gh cannot check or its state cannot be saved.

Included work: #2865 (issue #2857).

Agent cards, pasted images and orchestration

Agent tool calls render as cards headed → Delegating, ◎ Agent status, ↩ Agent answer, ✉ Messaging agent, ↻ Resuming agent and their siblings, with RUNNING, COMPLETED or FAILED p...

Gentle Shell v4.5.1 is a hotfix release. /gentle:music no longer offers to install a player that cannot run on native Windows, the persona states how to infer the reply language and bans every voseo form in neutral mode, unmatched profile keys get clearer notices, and the design canvas tests no longer hang the suite. The npm package remains gentle-pi, and the bundled Gentle AI runtime remains v4.3.1.

Provenance

• Previous stable: v4.5.0 → 19b4fade568d3499020c988573056f38b3bc05e4
• Release target: v4.5.1 → e8b2814934f98ded9199f49bde8f482c97eece3a
• Release validation: run 40671197740 passed package verification, published [email protected] to npm with provenance, built, verified and attached the installers, and verified the bundled distribution 4.5.1-1.4.0 on Ubuntu, Windows and macOS before attaching it.
• Pinned Gentle AI: v4.3.1 (2dba778); the review provider contract remains unchanged at 1.4.0, and the negotiated capability identity is unchanged.

What's new

No new features are declared for v4.5.1.

What was fixed

/gentle:music on native Windows

gentle-stream needs POSIX: it takes fcntl locks, listens on an AF_UNIX control socket and kills process groups, none of which exist on native Windows. In 4.5.0 a bundled install on Windows offered to download uv, Python 3.13 and the player (about 150 MB), which then could not start. On native Windows /gentle:music and its subcommands now say the player is not available yet and that it works inside WSL, and never offer, install or run anything. macOS, Linux and WSL are unchanged.

Included work: #2612 (issue #2611).

Reply language and voseo

The persona now says to judge the reply language by the user's latest message, never by earlier context or a compaction summary, and never to default to Spanish. Neutral mode bans voseo in regular and irregular verbs, with worked tú/usted replacements; the Gentleman persona keeps Rioplatense voseo.

Included work: #2610 (issues #55, #57, #125).

Profile key notices and hanging canvas tests

Notices for profile keys that match no agent now say the key is in the profile but no agent is configured with that name, instead of reading as if the profile were wrong. The design canvas event tests time out after 5 seconds with the buffered stream tail instead of hanging the whole unit stage when the inotify limit is exhausted.

Included work: #2602.

Pinned runtime

The pinned Gentle AI runtime is unchanged at github.com/gentleman-programming/gentle-ai/v3 v4.3.1: signed release archives on Darwin and Linux, and a SumDB-verified source build on Windows. The review provider contract remains 1.4.0; no NATIVE_CLI_CONTRACTS row or capabilities/vN identity was added. Bundled installs keep Pi 1.4.0.

Breaking changes

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

Upgrade

pi install npm:[email protected]

Restart Pi. No runtime migration is required. Bundled installs run gentle-shell upgrade.

Numbers

5 non-merge commits, 3 merged pull requests, and 2 unique GitHub PR authors since v4.5.0.

Verification

• Local suite (pnpm test, macOS arm64, Node 24) on the release commit: 7767 tests, 7656 pass, 75 skipped, 36 fail. The 36 are the pre-existing local-environment failures documented for v4.5.0 (PulseAudio fake-socket, agent-home config override, orchestrator-scope and one agents test), unchanged. The provider-contract and runtime-harness stages pass.
• PR CI for #2612: verify, tests on Ubuntu and Windows, installers on macOS, Ubuntu and Windows, review-repository-windows and session-transport-macos all passed; both CodeRabbit findings were fixed with tests (the Windows notice wins over the terminal-mode notice, and the music tests no longer depend on the host OS).
• The Windows behavior was test-first: the new test failed before the fix and passes after it, for opening, a mood, status and stop, with no offer, install or spawn.
• Package verification: 236 package resource files and 69 exact byte-pinned contract artifacts for the v4.3.1 runtime; npm pack --dry-run lists 966 files (11.7 MB packed).

Install

pi install npm:[email protected]

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

Full changelog: v4.5.0...v4.5.1

Gentle Shell v4.5.0 is a feature release. The models and profiles screens become one screen with profiles as tabs, opened by /gentle:profiles; the fullscreen rail gains a Jobs card; bundled installs move to Pi 1.4.0 and can install the newest published Pi with gentle-shell update --latest; and /gentle:music offers to install its player inside Gentle Shell. The npm package remains gentle-pi, and the bundled Gentle AI runtime remains v4.3.1.

Provenance

• Previous stable: v4.4.0 → b6c301c41b426ebb09cbd9dc3309cfceedcc1820
• Release target: v4.5.0 → 19b4fade568d3499020c988573056f38b3bc05e4
• Release validation: run 40606485076 passed package verification, published [email protected] to npm with provenance, built, verified and attached the installers, and verified the bundled distribution 4.5.0-1.4.0 on Ubuntu, Windows and macOS before attaching it.
• Pinned Gentle AI: v4.3.1 (2dba778); the review provider contract remains unchanged at 1.4.0, and the negotiated capability identity is unchanged.

What's new

One models and profiles screen

/gentle:profiles opens one screen with each profile as a tab (◉ this session, ★ default, ⌂ this repository) and the selected profile's routing as a table with the orchestrator first. Three actions apply it: Use in this session, Make default (the guarded global apply) and Save. It is pointer-first and keyboard-complete, offers only the effort levels each model supports, shows where Pi lands an unsupported saved level, and lists invalid or stale pins under the profile name. Switching tabs redraws in place. /gentle:profiles export <name>, import and publish <name> move profiles; /gentle:profiles export-routing and restore-routing move the global routing file.

Included work: #2588 (issue #2586), #2599 (issue #2598).

Jobs card in the fullscreen rail

Running background jobs get their own collapsible card, newest first, each with its elapsed time. Finished jobs stay for 60 seconds with ✓, ✗ or –, then the card clears itself. Click the header or press ctrl+shift+j to collapse it; GENTLE_PI_JOBS_KEY remaps or disables the shortcut.

Included work: #2592.

Newest Pi for bundled installs

Bundled installs now ship Pi 1.4.0, audited against every private Pi surface Gentle Shell relies on (the Vim editor's sources are byte-identical from 1.2.0 to 1.4.0). gentle-shell update --latest installs the newest published stable Pi without waiting for a Gentle Shell release: it warns that it skips the release's verified lockfile, verifies the new version like upgrade, keeps the previous one for gentle-shell upgrade --rollback, and never downgrades Pi. A later gentle-shell upgrade keeps that Pi until a newer Gentle Shell release arrives.

Included work: #2599 (issue #2598).

Music player on request

In a bundled install without gentle-stream or uv, /gentle:music asks before installing the player inside Gentle Shell: a pinned, checksum-verified uv 0.13.6 in runtime/, and the uv-managed Python 3.13 and gentle-stream in music/ (about 150 MB to download), isolated from any user uv, Python, pip or virtualenv settings and without needing git. Declining keeps the manual install hint, and pnpm or npm installs keep it unchanged. Sample voices still need the system FluidSynth library.

Included work: #2599 (issue #2598).

What was fixed

Bundled installs stuck on an older Pi

gentle-shell update in a bundled install redirected to gentle-shell upgrade, which installs only the Pi its Gentle Shell release pins, so a newer published Pi was unreachable. The pin moves to Pi 1.4.0 and --latest opens the newest published Pi on demand.

Included work: #2599 (issue #2598).

Profile tabs flickered

Switching profile tabs closed the screen and reopened it after reloading the model catalog, which painted the screen below for a frame. The panel now switches profiles in place.

Included work: #2599 (issue #2598).

Pinned runtime

The pinned Gentle AI runtime is unchanged at github.com/gentleman-programming/gentle-ai/v3 v4.3.1: signed release archives on Darwin and Linux, and a SumDB-verified source build on Windows. The review provider contract remains 1.4.0; no NATIVE_CLI_CONTRACTS row or capabilities/vN identity was added.

Breaking changes

• /gentle:models is retired: /gentle:profiles opens the same screen, and /gentle:models export|restore become /gentle:profiles export-routing|restore-routing.
• The separate models panel, profiles list and detail, routing editor and orchestrator picker are replaced by the one tabbed screen. Saved profiles and routing are unchanged.

Upgrade

pi install npm:[email protected]

Restart Pi. No runtime migration is required. Bundled installs run gentle-shell upgrade.

Numbers

7 non-merge commits, 3 merged pull requests, and 2 unique GitHub PR authors since v4.4.0.

Verification

• Local suite (pnpm test, macOS arm64, Node 24) on the release commit: 7761 tests, 7650 pass, 75 skipped, 36 fail. Every failure is pre-existing in that local environment (PulseAudio fake-socket, agent-home config override, orchestrator-scope and one agents test); the same suite on the pre-release main baseline fails 38 tests in the same files. The provider-contract and runtime-harness stages pass.
• PR CI for #2599: verify, tests on Ubuntu and Windows, installers on macOS, Ubuntu and Windows, and review-repository-windows all passed.
• Package verification: 236 package resource files and 69 exact byte-pinned contract artifacts for the v4.3.1 runtime; npm pack --dry-run lists 965 files (11.7 MB packed).
• Pi 1.4.0 audit: the Vim editor's editor.js, undo-stack.js and keys.js are byte-identical in Pi 1.2.0, 1.3.0 and 1.4.0; cli/args.js and the extension types are identical; the package-manager-cli.js and tui-alt-screen.js changes are compatible.
• Independent verification of gentle-shell update --latest: no blockers; 6175 update inputs without --latest produce identical plans before and after.
• Independent verification of the music install: no blockers; uv pins re-hashed; archive extraction rejects traversal and links; a corrupted download publishes nothing; nothing installs without consent. A real macOS arm64 install ran gentle-stream --help successfully.

Install

pi install npm:[email protected]

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

Full changelog: v4.4.0...v4.5.0

Gentle Shell v4.4.0 is a feature release. It adds Gentle Design, a provider-free local design canvas; optional local voice dictation; image paste in the editor; /gentle:music; and a super-yolo permission mode. It shares one global Engram server across sessions, makes the shell noticeably lighter per keystroke, and pins Gentle AI v4.3.1. The npm package remains gentle-pi.

Provenance

• Previous stable: v4.3.0 → d5d692a6888da9e9844e7e443ee30991fa4b9d14
• Release target: v4.4.0 → b6c301c41b426ebb09cbd9dc3309cfceedcc1820
• Release validation: run 40565556276 passed package verification, published [email protected] to npm with provenance, and built, verified and attached the installers on Ubuntu, Windows and macOS.
• Pinned Gentle AI: v4.3.1 (2dba778); the review provider contract remains unchanged at 1.4.0, and the negotiated capability identity is unchanged.

What's new

Gentle Design

/gentle:design and the gentle-design skill write self-contained HTML design directions under design/<slug>/ and open them on a local canvas. The canvas supports pinned comments with batch send and screenshots, navigation and focus modes, a design system board synced from the project's design tokens before the first design, and a handoff from an artboard to code that reports implementation progress and links designs to ODD features. It needs no external design provider.

Included work: #2562 (issue #2561), #2571.

Local voice dictation

Optional local dictation with Parakeet transcribes speech into the editor without a cloud service. Holding Space dictates when the push-to-talk toggle is on.

Included work: #2416 (issue #2413), #2418 (issue #2414).

Image paste, music, and the Agents rail

Pasted images become attachment chips with a preview, including on WSL. /gentle:music plays gentle-stream inside Gentle Shell. The fullscreen rail shows the Agents card with a collapsible header.

Included work: #2467 (issue #2464), #2496 (issue #2495), #2526 (issue #2525).

Super-yolo permission mode

A session-scoped super-yolo mode waives every permission dialog for the live primary session, except reads of private paths such as .env files, SSH keys, keychains and cloud credentials, which stay refused. It never answers provider consent or user questions on the human's behalf.

Included work: #2453 (issue #2452).

Session profiles

Profiles gain a disk corroboration reader, an append controller with failure quarantine, and controller lifecycle seams; the orchestrator model can be selected explicitly, and role and model_profiles keys that match no discovered agent are surfaced instead of silently ignored.

Included work: #1922, #1948, #1984, #2214 (issue #1478), #2397, #2405 (issue #2400), #2480, #2187.

A lighter shell

The status bar model, the changes digest and the changes widget paint are no longer rebuilt on every keystroke; presence publication is coalesced to the render cadence and its ancestor validation is asynchronous; the context backstop samples once per window; the working animation runs from real frames with a silence watchdog; the review mutation-ledger scan, the permission identity and the startup release lookup are cached; the task store and scratch ledger are bounded; and notifications reuse one persistent audio worker.

Included work: #2506 (issue #1681), #2521 (issue #2517), #2522 (issue #2518), #2524 (issue #2520), #2529 (issue #994), #2532 (issue #2530), #2533 (issue #2531), #2537 (issue #2519), #2542 (issue #2540), #2546 (issue #2543), #2547 (issue #2544), #2548 (issue #2545), #2551 (issue #2549).

Gentle AI v4.3.1 pin

Gentle Shell now installs and negotiates with Gentle AI v4.3.1, and the double-click installers embed it. See Pinned runtime.

Included work: #2587 (issue #2585).

What was fixed

One shared Engram server

Each session started its own Engram server. Sessions now share the global Engram server, its detached temp directory stays outside session scratch, and binding diagnostics are exposed without leaking private data.

Included work: #2481 (issue #2360), #2534 (issue #2468), #2415 (issue #2412).

Orchestration ceremony and review routing

Small tasks no longer pay for always-on ceremony, a Risk declaration that opens a sentence is admitted, refuter and validator use Pi's default model when unrouted, reviewer config typed before the binary resolves is refused, assessment continuations are clear when RDD is off, and answer-consent object input is serialized.

Included work: #2457, #2460, #2479 (issue #2271), #2494 (issue #2256), #2527 (issue #2500), #2387 (issue #2375).

Agents and subagents

Settled agents get an orderly shutdown before termination escalates; presence discovery ignores foreign-schema files and garbage-collects stale records when it overflows its cap; background capability is refused when the policy is off; forward-slash Windows repository_root values are accepted; and the current alias follows the published work topic.

Included work: #1775 (issue #1740), #2434 (issue #2433), #2502 (issue #2501), #2509, #2325 (issue #2314), #2554 (issue #2553).

Install, update, launcher and Windows

The main channel accepts a Gentle AI main commit that is a release tag, reinstalls from its recorded tarball, and installs a moved Shell when the Gentle AI step fails; updates show the package manager's error; Windows acquires the pinned Go when Gentle AI is already installed and hides the consoles of the last internal git launches; the launcher refuses cmd.exe arguments with a double quote and drops only the bundled npmCommand; storage metadata is read through native attributes; and companion updates stay under ordinary permission checks.

Included work: #2340 (issue #2301), #2347 (issue #2324), #2358 (issue #2356), #2374 (issue #2371), #2490 (issue #2489), #2445 (issue #967), #2484 (issue #2425), #2472 (issue #2469), #2474, #2470, #2381 (issue #2380).

Shell, editor and skills

External editor paths are passed without a shell; rail sections repaint on theme change; worktree-holder roots with no commits are skipped with one q...

Gentle Shell v4.3.0 is a feature release. It moves core orchestration rules from prompt text into the runtime, gives every session a runtime-owned scratch directory with an artifact ledger, renders the ODD steps from Gentle AI's published routing canon, and pins Gentle AI v4.2.0. It also stops headless sessions from stalling at the delivery question and fixes a long list of review, guard, launcher, and installer defects. The npm package remains gentle-pi.

Provenance

• Previous stable: v4.2.0 → c41ebd591358d393cf19c5ead981f67640a600ba
• Release target: v4.3.0 → d5d692a6888da9e9844e7e443ee30991fa4b9d14
• Release validation: run 38891394522 passed package verification and published [email protected] to npm with provenance.
• Pinned Gentle AI: v4.2.0 (4acaf42); the review provider contract moved from 1.3.0 to 1.4.0 (adds routing/pi.md), and the negotiated capability identity is unchanged.

What's new

Orchestration rules enforced by the runtime

Several rules that used to live only in the orchestrator prompt are now runtime checks. The parent session gets a context backstop sized to the model, min(150k, 0.15 × context window), configurable with GENTLE_PI_CONTEXT_BACKSTOP_TOKENS and GENTLE_PI_CONTEXT_BACKSTOP_FRACTION. Verifier launches pass an admission check, so small tasks no longer get a verifier they do not need. Todo progress updates itself from task counts, each subagent gets its own TMPDIR, a commit-slice signal flags oversized work units, and a guard lints delivered tests. Bench runs measured the change as cost-neutral or cheaper, with no quality loss in blind review.

Included work: #2290 (issue #2289).

Leaner orchestration

The orchestrator verifies only on a named risk, delegates units of behavior instead of files, and runs a differential check on the commands a change preserves. It also cuts turns and context per call, commits per reviewable slice, keeps small tasks inline, and enforces small-task inline work when a writer is admitted.

Included work: #2246 (issue #2245), #2275 (issue #2274), #2279 (issue #2278).

ODD steps from the Gentle AI routing canon

The harness renders its ODD protocol steps from the routing/pi.md block that Gentle AI publishes in its provider contract, so Gentle Shell and Gentle AI share one source instead of a hand-maintained copy.

Included work: #2293 (issue #2292).

Session scratch and artifact ledger

Each primary session now runs with its own scratch directory (gpXXXXXX) as TMPDIR, and subagents get gaXXXXXX directories under it. The names are short so Unix socket paths stay within the macOS limit. A JSON ledger under the config home records the scratch and every clone or worktree a session creates. The runtime removes the scratch at shutdown, sweeps scratch left by ended sessions, and offers /gentle:scratch list and /gentle:scratch clean for the recorded artifacts. It never removes a directory a live session still uses.

Included work: #2300 (issue #2298).

Gentle AI v4.2.0 pin

Gentle Shell now installs and negotiates with Gentle AI v4.2.0. See Pinned runtime.

Included work: #2317 (issue #2316).

Shell, launcher, and profile improvements

/gentle:changes opens full screen with a diff-only toggle, and gentle-shell home import-pi imports an existing Pi setup. The doctor surfaces the Herdr task-summary sidebar setup, and new theme roles cover the usage gauges. Profiles record where a task's resolved model came from and tell a bound session when its profile definition changed. On Windows, review reuses the creation-local owner identity.

Included work: #2218, #2220, #2205 (issue #2071), #2307 (issue #2222), #2184 (issue #2180), #2231 (issue #2228), #2262 (issue #2074).

What was fixed

Headless sessions no longer stop at the delivery question

When the orchestrator forecast more than about 400 changed lines in a session where no human can answer (pi -p, pi --mode json, or pi --mode rpc without GENTLE_SHELL_INTERACTIVE_HOST=1), it asked how to shape the pull requests before writing any code. ask_user_question was unavailable, so the session printed the menu and stopped. Such sessions now use feature-branch-chain without asking and record the choice in the feature document. In the bench, six headless x6 runs had no stops, against 4 of 10 before.

Included work: #2321 (issue #2320).

Session scratch cleanup keeps everything still in use

Review findings on the first scratch release showed cleanup could remove too much. Shutdown and clean now keep the TMPDIR of a subagent that is still running or quarantined. A reused pid is detected by the operating system's own start token, compared exactly and never through the wall clock, so a clock step cannot make a live session look ended. A clone with linked worktrees is kept, clean keeps entries changed in the last minute, and a reload restores the inherited TMPDIR from the ledger.

Included work: #2318 (issue #2315).

Review

Native review tools called from inside another tool (for example from codemode) hung the session; the runtime now refuses them. Candidate view directories that macOS File Provider reset to 0700 are repaired. The RDD status line stays pinned per session until the off state changes, the status-unavailable notice names its cause, grouped STATUS failures keep their diagnostics, and the verification scope and auxiliary gates are bounded.

Included work: #2299 (issue #2297), #2244 (issues #707, #826), #2247, #2251 (issue #2250), #2260 (issue #1917), #2198 (issue #2103).

Guards and YOLO mode

The destructive-command guard now recognizes commands after shell reserved words, inside backticks, and in eval. YOLO mode stops asking about removing its own temp scratch and about harmless pushes.

Included work: #2286 (issue #2285), #2284 (issue #2282).

Launcher, installer, and bundled Shell

Updates can replace a Pi older than the required minimum. Standalone Gentle Shell gets its own config home, and memory created by the Shell is recovered with session-owned servers required. gentle-shell mcp forwards to Pi's own command, and setup asks Gentle AI to skip the launcher-owned gentle-pi. Windows installs explain Smart App Control blocks instead of suggesting network fixes.

Included work: #2283 (issue #2281), #2207 (issue #2201), #2199, #2204 (issue #2140), #2223 (issue #2143), #2230 (issue #2229).

Agents, tools, and UI

Agents avoid repeated Git probes when recency reorders, keep non-Git discovery errors out of the terminal, and label live peers that predate discovery publication. CodeGraph artifacts and test scratch stay out of delivered diffs. Todo state no longer breaks prompt prefix caching with duplicate trailing state. /gentle:changes marks untracked new files U, banner settings stay under Customization, and quiet tools isolate the last path component when delegating an expanded read with an image.

Included work: #2068 (issue #2020), #2265 (issue #1145), #2309 (issue #2305), #2249 (issue #2248), #2234 (issue #2195), #2202 (issue #2200), #2217 (issue #1664), #1802 (issue #1620).

Tests and docs

Windows bootstrap timing is traced and review fixtures are isolated. The README has a new presentation, structure, and visuals.

Included work: [#2261](https://github.com/Gent...

Gentle Shell v4.2.0 is a compatibility and reliability release: it moves the Pi floor to 1.2.0, ships a gentle-shell update that really refreshes the Pi a Shell installation runs, keeps the private Vim prompt working with Pi 1.2's new cursor rendering, and carries the bundled Engram core 3.4.0 with an honest disabled-memory notice. The npm package remains gentle-pi, and the bundled Gentle AI runtime remains v4.1.1.

Provenance

• Previous stable: v4.1.0 → 79323b76aa900c1cb88135fb0d95c04899c1b9c0
• Release target: v4.2.0 → c41ebd591358d393cf19c5ead981f67640a600ba
• Release validation: run 38392923994 passed package verification, published to npm with signed provenance, built and attached the installer bundles and the distribution assets, and verified the distribution on Linux, macOS and Windows (the distribution job was rerun once after an npm registry read lag; no second publish).
• Pinned Gentle AI: v4.1.1; the review provider contract remains unchanged.

What's new

Pi 1.2.0 floor and development ranges

Gentle Shell now requires Pi 1.2.0 or newer: the launcher's version gate, the @earendil-works/pi-coding-agent peer range, the installer's pinned Pi (PI_INSTALL_VERSION) and the development ranges all move to >=1.2.0, and the package resolves the Pi 1.2.0 trio for its own tests. Older Pi runtimes found on PATH are refused with a message naming the found and required versions; the installer and gentle-shell update bring installations to 1.2.0 themselves. Included work: #2177 (issue #1796) and the release preparation #2181.

gentle-shell update refreshes the Pi this launcher runs

gentle-shell update no longer forwards Pi's own self-update, which refuses pnpm linked-store installations ("pi cannot self-update this installation"). Shell now proves which global package supplies the exact Pi executable it runs, from the package manager's global listing and canonical paths, and reinstalls only that package: a global Pi for PATH or GENTLE_SHELL_PI runtimes (package-manager shims are followed to the cli.js they name), or the gentle-pi package itself, at its current version, when Pi is Shell's adjacent peer, because updating a separate global Pi never changes the peer a Shell installation runs. Unknown, ambiguous, linked-source or shared-group ownership refuses without touching anything; Pi and Shell are never combined into one install. After the install Shell reads the supplied Pi version back and reports it, naming pnpm's minimumReleaseAge rule when a very recent release is still held back. Included work: #2177 and #2179 (issue #1796).

Session profiles

Shell records a session profile frozen at startup and routes launches, status and Usage through it, with a v1 record codec and active-branch replay. Included work: #1918, #1919, #1827, #2007 (issue #1064).

YOLO sessions waive reversible pushes

A YOLO session's standing permission now covers every reversible push and non-interactive rebase. Included work: #2173.

What was fixed

Engram memory disabled with an unverifiable store

Root cause: the bundled Engram core could not answer GET /compatibility, so a pre-existing global Engram server or store could never be proven safe and Shell disabled memory with a notice that suggested an update which could not help. Shell now ships the compatibility-enabled Engram core 3.4.0, its notice no longer implies that updating Shell alone fixes a running server, and when the running global server is older than 3.4.0 the notice names that server's version and asks to update and restart it. Memory is enabled only when a server verifies the store through /compatibility or the store is Shell's own; an older global server still has to be updated by the user. Included work: #2138, #2139, #2142 (issue #2137).

Vim prompt with Pi 1.2

Root cause: Pi 1.2 renders its fake cursor through paired APC markers that the host resolves later, instead of inline SGR, which broke selection inversion and empty-prompt hints in the private Vim adapter. The adapter now admits the audited 1.2.0 pair, keeps the markers intact so the host can suppress the software cursor, closes selection before a boundary cursor and re-arms it after. Included work: #2177.

Startup, prompt cache and guards

The Todo state and its stale counter stay out of the system prompt so prefix caching survives (#2171, #1369); the last known RDD status line is kept when the native re-read fails (#2168); Auto permission checks recover with bounded evidence and live intent (#2158); the command guard ignores guarded words inside data-command arguments (#2175); already authorized work continues without a new permission prompt (#2161); Changes excludes untracked dependency backups (#2170); Todo scroll shortcuts leave Pi's prompt navigation keys alone (#2155).

Pinned runtime

The bundled Gentle AI runtime is unchanged at v4.1.1 (github.com/gentleman-programming/gentle-ai/v3), with signed archives for Darwin and Linux and the SumDB-verified source build for Windows; the review provider contract remains 1.3.0 and no new NATIVE_CLI_CONTRACTS row or capabilities/vN identity was added. The bundled Engram core moves to 3.4.0.

Breaking changes

• Pi 1.2.0 is now the minimum: a pi older than 1.2.0 found on PATH or through GENTLE_SHELL_PI exits with a message naming both versions. Installer-managed and adjacent-peer installations are moved to 1.2.0 by the installer or gentle-shell update.

Upgrade

pi install npm:[email protected]

Restart Pi. No runtime migration is required: the pinned Gentle AI runtime and its managed assets are unchanged.

Numbers

30 non-merge commits, 21 merged pull requests, and 4 unique GitHub PR authors since v4.1.0. Release preparation: #2181 (issue #1796).

Verification

• Local unit suite on the release-preparation head (macOS, direct Node): 6,668 tests, 6,586 passed, 0 failed, 82 platform skips; typecheck 0 diagnostics; generated runtime matches sources (15 modules).
• Package verification: 209 files, 69 exact byte-pinned contract artifacts for the v4.1.1 runtime; provider contract mirror 1.3.0; npm pack --dry-run 856 files.
• Required CI on every merged pull request of this window passed on Linux, macOS and Windows, including the installer suites and the packed-package verification.
• gentle-shell update was exercised end to end on a real isolated pnpm 11 global installation (packed build served through a local registry proxy): adjacent-peer refresh, shim override, --all, and the minimumReleaseAge readback; an independent verifier repeated the run on the final bytes.
• Native review: not run for this window (reviewDue: false on every candidate); independent verifiers covered the high-risk changes instead.
• The packed-runner E2E against the published release assets runs inside publish.yml.

Install

pi install npm:[email protected]

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

Full changelog: v4.1.0...v4.2.0

Gentle Shell v4.1.0 is a minor release. Clean machines can now install Gentle Shell from a browser wizard or a double-click installer, and new release setups run as a self-contained bundled Gentle Shell with its own Pi, Gentle AI, Engram, and state. The first field reports are fixed: Windows setup no longer fails on pi install npm:gentle-pi, macOS no longer needs Homebrew, and the first launch no longer installs everything twice. The release also adds native background jobs and monitors, contextual Auto permissions, cross-session coordination, and session-bound profiles, and it pins Gentle AI v4.1.1. The npm package remains gentle-pi.

Provenance

• Previous stable: v4.0.0 → 1f35ab1e4ff78f41ce6102cd961e7889a9f1cf69
• Release target: v4.1.0 → 79323b76aa900c1cb88135fb0d95c04899c1b9c0
• Release validation: run 38252924051 passed package verification, published to npm with provenance, attached the verified installers, and verified the bundled distribution on Linux, macOS, and Windows.
• Pinned Gentle AI: v4.1.1 (898d3976e); the review provider contract moves from 1.2.0 to 1.3.0.

What's new

Install Gentle Shell on a clean machine

A browser installation wizard checks the machine, shows one plan, and asks once before it changes anything. It installs what is missing, updates an existing Gentle Shell, and replaces older tools or reuses version-managed ones such as mise. Every release now carries unsigned double-click installers for macOS, Windows, and Linux. When Go is missing or older, the installer downloads a pinned Go to build Gentle AI. Windows has the same coverage as macOS and Linux, including private storage when %LOCALAPPDATA% is shared and the real error when a build fails. A missing Git is a notice before consent, never a blocker. Installs can also follow the latest main channel.

Included work: #1703 (issue #1700), #1975, #1962, #1995 (issue #1994), #2000 (issue #1999), #2024 (issue #2023), #1959, #2120 (issue #2119).

Bundled Gentle Shell

New release setups install a bundled Gentle Shell: one prefix holds its exact Pi, its pinned Gentle AI, Engram, and their state, so another Pi or Gentle AI on the machine cannot change it. The release publishes the bundled distribution manifest and lockfile it installs from. Existing global installs can migrate into the bundled prefix. The bundled launcher offers updates before interactive startup, gentle-shell self-uninstall removes it and reverts its PATH entry, and Engram memory starts only when the Shell can prove it owns the store.

Included work: #2060 (issue #2059), #2066 (issue #2065), #2070 (issue #2069), #2076 (issue #2075), #2088 (issue #2087), #2091 (issue #2090), #2093 (issue #2092), #2098 (issue #2097), #2042 (issue #2041), #2125 (issue #2100).

Background jobs and monitors

bash_background runs a command in the background and wakes the agent once when it exits, with bounded output and logs. monitor turns each output line of a long-running command into an event, and stop notices name the limit and the log path. Background completions the parent was told not to poll are never lost, and a standalone sleep is refused while background work is active.

Included work: #1835 (issue #1171), #1844 (issue #1843), #1842 (issues #1840, #1841), #1845, #1888 (issue #1887), #1833 (issues #1092, #1821), #2028 (issue #1903).

Contextual Auto permissions

The Auto permission mode decides with the conversation's context, including image input, and retries provider failures. Each session can start from a persistent default mode.

Included work: #2102 (issue #2101), #2111 (issue #2110).

Cross-session coordination

Sessions publish a recognizable subject, initial and current task aliases, their repository scope, curated state, and a bounded classification of their work. Other sessions can list, search, filter, and relate that work, and read published state or ask for bounded reasoning only with explicit cost permission. Messages between orchestrators render as recognizable cards, and each agent publishes its declared tool inventory so routing can check capabilities.

Included work: #1714 (issue #1701), #1715, #1720, #1724, #1729, #1733, #1734, #1735, #1736, #1737, #1738, #1779, #1780, #1785, #1786, #1789, #1795, #1893 (issue #1890), #1960, #1998 (issue #1996).

Session-bound profiles

The active profile binds to the parent session: launches, status, and usage resolve that binding, the live orchestrator switches when a profile is applied, and the inherited profile is frozen at startup with an optional follow mode and a drift notice. Orchestrator and reviewer routing apply per session.

Included work: #1557, #1558 (issue #1064), #1824, #1825, #1826, #1837, #1856 (issue #1220), #1886, #1699 (issue #1683), #1384 (issue #1349).

Review by risk, with agent-selected lenses

The agent's lens selection is forwarded to native START, so a review runs only the lenses that fit what changed. Verification follows the risk tier in every RDD state, and the reminder appears only for reviews that are due.

Included work: #1849 (issue #1848), #1852 (issue #1851).

ODD and orchestration

The orchestrator delegates for a named reason, not for size. Handoffs pass the user's spec by reference, tasks are sized by understanding, risk, and resumability, and bounded short checks run synchronously. Small direct tasks need no subject declaration. Todo cards gain blocked and dropped statuses, stay compact and scrollable, and the model is reminded to review the plan during long runs. Tool cards are readable, bounded, and theme-aware, and Shell cards can show minimal content. Delegated children receive the gentle-pi package and skip parent-only startup work.

Included work: #1794 (issue #1731), #1718 (issue #1713), [#1721](https:...

Gentle Shell v4.0.0 is a major release. It pins Gentle AI v4.0.0, makes Organic Driven Development (ODD) the only development workflow, raises the Pi baseline to 0.99.1, and tracks Pi 1.0. It also adds a guarded session YOLO mode, opt-in Vim prompt editing, opt-in prompt history, a /gentle:customize panel with float-style cards, /gentle:stats, and a first-party NaN provider. Fixes cover subagent delivery, native review capture, the launcher, and shell panels. The npm package remains gentle-pi.

Provenance

• Previous stable: v3.7.0 → 59257bff7023b44837cd4ff3edc3807f777be458
• Release target: v4.0.0 → 1f35ab1e4ff78f41ce6102cd961e7889a9f1cf69
• Release validation: run 36928716621 passed package verification and published [email protected] to npm with provenance.
• Pinned Gentle AI: v4.0.0 (ff77164d). review-integration/v2 with capabilities/v2.6 and provider contract 1.2.0 remain unchanged.

What's new

ODD is the only development workflow

Gentle Shell retires its SDD and OpenSpec routes, commands, agents, and packaged resources, and keeps ODD as the single development workflow. Native review (RDD) stays independent. User-edited or unknown-provenance assets are retained during installation and migration instead of being inferred from names or template content. For behavior changes with meaningful runnable tests, applicable RED → GREEN → refactor is now the default. Cases where it does not apply are explained and checked proportionately, and the separate Strict TDD gate is gone from parent, worker, verifier, and skill guidance.

Delegated children now load a minimal context extension that filters orchestrator-only managed blocks out of their context files. Measured live, a delegated explorer starts at about 57k tokens instead of about 87k. Delegation follows an evidence budget instead of file counts: work stays inline only for one parallel batch of at most 3 calls and about 10k tokens; larger mapping goes to one explorer that returns a bounded path:line handoff. For oversized changes, delivery guidance now offers three ordered outcomes: a feature/tracker chain, a verified default-branch chain, or a single PR as the least recommended option. The choice wording follows the user's conversation language, and size labels apply only under the destination repository's actual policy.

Included work: #1408 (issue #1405), #1428 (issue #1427), #1590 (issue #1587), #1600 (issue #1599).

Gentle AI v4.0.0 pin and Pi 1.0

The package-local runtime now uses the signed Gentle AI v4.0.0 release at the /v4 module path; see Pinned runtime.

Gentle Shell now requires Pi 0.99.1 or later and Node 22.19.0 or later. Pi host packages are optional peers, and the adjacent Pi CLI is resolved through its public entry. Pi 0.99.1 OKHSL theme previews are supported. Observed codemode calls render as compact cards without replacing execution, schema, activation, or loadout.

Development tracking moved from exact pins to an open range, first >=0.99.2 and now >=1.0.0. A 72-hour minimumReleaseAge filter stays in place as the supply-chain guard, which also removes the stale "update pi" banner. After a touched-contract audit and bundled and unbundled behavioral tests, the private Vim editor adapter admits exact Pi 1.0.0. The runtime and peer minimum stays at 0.99.1.

An earlier step added a deterministic long-conversation fullscreen and sidebar scroll benchmark with exact frame-parity coverage. That work does not claim to fix the reported live scrolling pause.

Included work: #1644 (issue #1643), #1642 (issue #1641), #1624 (issue #1623), #1582 (issue #1581), #1426 (issue #1424).

Guarded YOLO mode and messaging consent

/gentle:yolo adds a session-only, human-activated mode. While it is on, ordinary scoped work, commits, non-force pushes, and PR creation stop asking for repeated permission. Run with no argument in the interactive UI, it opens a select menu; enable, disable, and status work as arguments, and the same toggle appears in /gentle:customize → Editor. Activation is limited to the interactive primary TUI in an identifiable Git clone. A menu choice is bound to the session that opened it: if the session changes while the menu is open, the choice is discarded and reported. Shared destructive-command guards apply regardless of the mode. Recognized data loss, such as DROP, TRUNCATE, unbounded DELETE, broad rm -r, and destructive Git, always needs fresh confirmation in the primary session and is blocked in delegated subagents.

Separately, orchestrator_send_message now needs explicit user consent before it messages another session. The consent dialog offers Allow once, Allow for this session, or Deny. Headless runs, a cancelled dialog, and a replaced session fail closed. Contributed by @carlosmoradev.

Included work: #1603 (issue #1602), #1609 (issue #1608), #1616 (issue #1615), #1372 (issue #1364).

Vim prompt editing and native selection keys

/gentle:vim adds opt-in, persistent Vim editing to the Gentle-owned Pi prompt and never replaces foreign editors. It supports NORMAL and character or line VISUAL modes, motions, operators, text objects, registers, undo, and repeat. Pi slash-command and skill completion keep working, and Escape keeps its two-stage behavior. /gentle:customize gains an Editor category that controls the same preference.

@carolitascl added native selection keys to the petal prompt: Shift+Home and Shift+End anchored selection, Alt+A select-all, and replace-on-key with a visible highlight. If Pi's editor internals drift, the selection engine falls back to plain passthrough instead of crashing.

@dnlrsls fixed a crash on git installs. The Vim adapter read Pi TUI metadata with a CommonJS require that cannot resolve without an extension-local copy, which took down the shell and agents extensions. An unresolvable host now falls back to ordinary editing. @carlosmoradev made Vim runtime detection match Windows path separators.

Included work: #1415 (issue #1413), #1421 (issue #1419), #1402, #1594 (issues #1586, #1589), #1464 (issue #1458).

Visual customization and float-style cards

/gentle:customize brings together animation and banner controls, installed-theme previews with an explicit apply step, a responsive layout with section visibility, and validated named profiles. Creating, editing, importing, and exporting custom themes is out of scope.

Float is now the default card style; an explicitly saved neon preference is kept. The float style also covers the shell chrome: Agents, Todos, Status, the prompt, and the bars above and below the input. Tool, Code, and Gentle AI cards share one outlined frame with per-kind icons and useful collapsed previews. Agent result cards lead with the subagent's answer or error. Quiet tool calls render as cards whose frame tone follows the lifecycle: running, done, or failed. The bundled themes give the user prompt its own tinted surface. @carolitascl added a live call duration to Gentle AI cards that freezes once the call completes.

Included work: #1411 (issue #1409), #1614 and #1628 (issue [#1613](https://github.com/Gentle...