gentle-pi v4.6.0 — An IDE Inside the Terminal and Model Fallback Chains

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 gentle-pi@4.6.0 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 pills and an iris tint while in progress. A subagent_run that throws now reads as FAILED, and the delegation header names the launch provider/model · effort (or inherit). Pasting only image paths (up to eight: absolute, ~/, file:// or quoted) turns each into an [Image#N] chip, typed by the file's signature; any other paste reaches Pi unchanged.

When a turn declares Risk: item N and settles without launching gentle-ai-verify, the orchestrator now shows a visible, non-blocking reminder. orchestrator_list flags peers whose work state was never published, and publishing it on every task change is required. AgentEndEvent.errorCategory exposes a closed set (auth, rate_limit, quota, context_length, timeout, network, provider_unavailable, invalid_request, unavailable), codemode sessions get seven thin-orchestration guidelines, Herdr task-summary preferences gain their store ahead of a later UI, and the native MCP status API (pi.getMcpStatus(), pi.onMcpStatusChanged()) is documented for extensions.

Included work: #2616, #2694 (issue #2695), #2744 (issue #2743), #2653 (issue #2652), #2634 (issue #2633), #2419 (issue #2322), #2835 (issue #2834), #2619, #2734 (issue #2303).

Pi 1.5.0 for bundled installs

Bundled installs now ship Pi 1.5.0, and the bundled distribution is 4.6.0-1.5.0.

Included work: #2749 (issue #2748).

What was fixed

Scrolling froze long fullscreen conversations

Scrolling a long fullscreen conversation with the mouse wheel, or just moving the mouse over it, could freeze Gentle Shell: the sidebar's root hover fallback delegated to Container.prototype.handleMouse, which renders every transcript child to measure it, so each mouse event re-rendered the whole conversation. The fallback now delegates only to a handler the root sets on itself, and the hover still clears on move.

Included work: #2869 (issue #2868).

Claude bridge turns cost nothing

pi-claude-bridge records every turn at $0, child processes left the shell before registering the cost hook, and usage snapshots were filed under anthropic while the bar looked up claude-bridge (no subscription usage for this provider). Bridge turns are now priced at the Anthropic list price and shown as sub, children register the hook before the shell guard so the Stats agents row adds up, and snapshots are filed under the serving provider.

Included work: #2843 (issue #2842), #2848 (issue #2846), #2287 (issue #1399).

Package agents froze on old instructions

A package agent whose frontmatter had been rewritten fell out of the manifest and kept its old instructions, and a forced refresh would have undone a user's frontmatter edits, such as removing bash from tools:. Agents are now recognized by their body's sha256: a stale body is replaced with the current one while model: and thinking: are kept, and an agent whose body matches is left alone.

Included work: #2851 (issue #2849), #2854.

Sensitive paths and private history

The sensitive-path deny list covered only read, write and edit, and the prompt-history store was created with the default umask (0644 files, 0755 directories). grep, find and ls now deny the same paths, and history is written 0600/0700, existing histories on their next rewrite. grep with --hidden over . can still reach an untracked .env, and bash is not covered.

Included work: #2364, #2656 (issue #2424).

Review

Reviewers route through the session profile; each in-process reviewer completion gets its own session id and the resolved provider endpoint and environment; correction captures bound to the frozen authority target and provider-issued target selectors are accepted; cheap candidate-view invariants are checked before START is advertised; ambient inspect accepts empty input; safe symlink targets accept a trailing slash; preparation errors keep their errno; and ineffective Windows orphan sweeps are skipped.

Included work: #2720, #2342 (issue #1646), #1831 (issue #1830), #2658, #2657, #2352 (issue #2196), #1677, #1822 (issue #1811), #2388 (issue #2376), #2343 (issue #2269).

Shell interface

Explicit binding routing carried non-role keys, which printed Warning: "orchestrator" did not match any agent, and clicking an agent row did nothing; routing is now filtered to roles and the click opens /gentle:agents. Footer, sidebar and timer resources outlived /reload and are now released on shutdown. Activity shows below agents in a narrow sidebar, the header keeps its effort when the location does not fit, long Customize input wraps, option previews stay within the terminal height, the startup logo degrades on narrow terminals, the todo scroll hint names alt+shift, the agents thread scroll clamps at the bottom, and provider review roles are no longer reported as unmatched at launch.

Included work: #2847 (issue #2684), #2837, #2639, #2277 (issue #1977), #2594 (issue #2270), #1385 (issue #1340), #1265 (issue #1264), #2182 (issue #2159), #1818 (issue #1293), #2666 (issue #2430).

Orchestration and reply language

Work continuity and informed approval are preserved without needless permission prompts, cumulative explorer routing is restored, named-agent runs are no longer reminded at settle, verifier preparation is bounded without repair loops, recursive scans in worker and verify prompts stay inside source directories, orchestration descriptions fit byte budgets, and the human's reply language survives harness turns and native subagent wakes.

Included work: #2638 and #2673 (issue #2211), #2701 (issue #2687), #2654, #2641, #2746 (issue #2686), #2672, #2664 (issue #2348), #2814 (issue #2812).

Platforms, installer and providers

The workspace guard compared paths as strings, so a mapped drive (Z:\test) never matched its UNC Git toplevel (\\server\share\test); it now compares file identity. The updater accepts a source-linked Pi it owns with any pnpm at or above the declared 11.1.1, and DeepSeek V4 Flash's output cap rises from 16,384 to 131,072 tokens, because NaN counts reasoning against max_tokens and reviewers ran out with reviewer-empty-output. Stale Windows session presence is reclaimed safely, the installer's bootstrap tools guard accepts xattr and SELinux mode markers, Herdr identifies Gentle Shell as its own agent, and the skill registry degrades truthfully when storage is unwritable.

Included work: #2628 (issue #2558), #2650 (issue #2649), #2844 (issue #2840), #2267, #2254 (issue #2144), #2728 (issue #2705), #2624 (issue #373).

CI and tests

CI binds checkout identity to the immutable run merge, avoids duplicate installer tests and obsolete PR runs, and never auto-closes approved or high-priority issues. Tests pin unit-stage Git config files, keep the Windows diagnostics fixture outside the repository, pin packaged agent tool allowlists, and pin the fail-closed launch contract without a session manager.

Included work: #2670, #2707, #2667, #2636 (issue #2552), #2621 (issue #2620), #2617 (issue #62), #2681 (issue #1709).

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

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

Upgrade

pi install npm:gentle-pi@4.6.0

Restart Pi. No runtime migration is required. Bundled installs run gentle-shell upgrade. Going back to an earlier version: it rejects a visual-customization.json that carries the new stats key and falls back to the defaults, and it keeps reading profiles.json without fallback chains.

Numbers

143 non-merge commits, 86 merged pull requests, and 16 unique GitHub PR authors since v4.5.1.

Verification

• Local suite (node scripts/run-test-suite.mjs, macOS arm64, Node 24, clean environment) on the release commit: 8401 tests, 8322 pass, 78 skipped, 1 fail. The failure is the timing-sensitive public SDK publishes, consults, pages, withdraws and replaces isolated owners in tests/orchestrator-consultation-sdk.test.ts, where an activity publish adds two Git probes mid-count; it also fails intermittently on the pre-release baseline and passes 3 of 3 runs on its own. The provider-contract and runtime-harness stages pass.
• PR CI for #2865 and #2869: verify, tests on Ubuntu and Windows, session-transport on macOS, review-routing-focused and review-repository on Windows, and installers on macOS, Ubuntu and Windows all passed (the macOS installer job of #2865 was rerun after GitHub could not acquire a hosted runner).
• Package verification: 238 package resource files and 69 exact byte-pinned contract artifacts for the v4.3.1 runtime; npm pack --dry-run lists 1058 files (12.0 MB packed, 25.3 MB unpacked).
• GitHub star prompt: 26 focused tests (all passing on the release commit) cover default gh starring, the browser fallback, the 404-on-PUT case, the [star] hover and click, and every responsive wording width.
• Scroll freeze: a regression test on a real Container root proves wheel and move events render no transcript child while move still clears the hover; a CPU profile of a frozen session spent 92% of its time in that path before the fix.

Install

pi install npm:gentle-pi@4.6.0

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

Full changelog: v4.5.1...v4.6.0