gentle-pi v4.0.0 — Gentle AI v4, ODD-Only Shell, and Pi 1.0 Support

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 gentle-pi@4.0.0 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), #1605 (issue #1604), #1533 (issue #1532), #1535 (issue #1534), #1317 (issue #1315).

Prompt history

@carolitascl delivered prompt history as a reviewed chain of slices:

• a per-instance JSONL store with project identity;
• read, ordering, deduplication, and project or global query APIs;
• migration and seeding from Pi session transcripts;
• tombstone-backed deletion that transcript re-seeding cannot undo;
• garbage collection and compaction that is safe with concurrent writers;
• a selector opened with /history or Ctrl+Shift+R, with search, list windowing, a preview, and mouse handling.

Capture is off by default. It is enabled from Customize → History. An explicit GENTLE_PI_HISTORY_CAPTURE value takes precedence over the saved preference, and an invalid preference fails closed. Turning capture off never deletes history.

Follow-up work restored the responsive selector header and sidebar-aware margin. It also hardened garbage collection and deletion and made Home and End aware of the search query.

Included work: #1390, #1392, #1391, #1393, #1394 (issue #818), #1453, #1454, #1455, #1475 (issue #1474), #1480 (issue #1479), #1477 (issue #1476), #1482 (issue #1481).

ODD phase labels, RDD sidebar, and quieter agent activity

While the orchestrator works, the Gentle input shows the current ODD phase, such as exploring, planning, implementing, or checking. The label is inferred from the primary session's tool activity, and explicit gentle_odd_phase reports refine it. Routine successful phase reports no longer add transcript rows. Delegated worker, verifier, and explorer roles keep their work-phase label, and CI polling with gh pr checks or gh run view|watch|list reads as checking.

@MarsSall delivered the display-only 🌹 RDD Status block in four slices: the contract and renderer, correlated publication, runtime and session-reset wiring, and display edge cases. Follow-ups describe each state by what is happening, for example Needs your consent or ✓ Approved. A new Sections toggle hides the block, and review cancellation is classified from the thrown error.

Running subagent_result polls no longer render transcript rows. @danielgap made presence polling reuse unchanged remote thread items, so their cached rendering is hit.

Included work: #1440 (issue #1438), #1450, #1506, #1523, #1512, #1319, #1379, #1500, #1510 (issue #1306), #1508, #1507, #1511, #1468 (issue #1467), #1435 (issue #1011).

First-party NaN provider

@decode2 added nan as a first-party provider. It uses Pi's OpenAI-compatible streaming and API-key resolution with no external provider package, and it discovers the documented chat models available to the current key. API-key login goes through Pi's native Provider API: empty input is rejected and valid input is trimmed. All seven documented chat models stay available offline. Each model maps Pi thinking levels to the reasoning_effort values it accepts. GLM 5.3 advertises image input, and output caps are raised so that reasoning does not starve the answer.

Included work: #1570, #1571 (issue #1569), #1637 (issue #1635).

Usage statistics and a Gentle Shell resume command

/gentle:stats opens a fullscreen panel with Overview, Models, and Session tabs. It derives usage history, model distribution, a heatmap, streaks, and session totals from existing local JSONL files. Gentle Shell and original Pi histories are combined and sessions are deduplicated.

When gentle-shell exits, @matraket's change prints gentle-shell --session <id> below Pi's own resume line. The command keeps the home selector and a custom session directory. It is printed only to a TTY, and on Windows only when the command can be quoted safely. This is a workaround until Pi provides an equivalent.

Included work: #1630 (issue #1629), #1515 (issue #1503), #1516.

What was fixed

Subagent delivery and lifecycle

• Idle parents. Child output delivered to an idle parent bypassed the normal prompt lifecycle. It is now stored durably and wakes the parent through that lifecycle, which preserves before_agent_start and prompt capture.
• Mid-session Pi upgrades. Upgrading Pi mid-session deleted the cli.js path captured at load, so later subagents failed with MODULE_NOT_FOUND. The Pi entry is now re-resolved before each spawn.
• Idle watchdog. Streamed tool arguments now count as progress, so the watchdog no longer misreads them as silence.
• Stale messages. @decode2 replaced follow-up delivery with an owned queue. Subagent notifications and queries arrive by steering at turn boundaries and are invalidated when their task settles, so stale messages no longer reach later turns.
• Large instructions. @carlosmoradev moved child instructions over 1,000 characters into an owner-only temporary file. Passed inline, they could kill the child before RPC startup. Runner diagnostics now keep the exit signal.
• Costs and child sessions. @carlosmoradev also aligned subagent cost formatting with the header and kept review reminders and primary prompts out of child sessions.
• Blank root selector. @rjoleinik made a blank root selector count as absent, so callers that send empty optional strings can delegate.

Included work: #1631 (issue #1528), #1576 (issue #1568), #1566 (issue #1562), #1461 (issue #1162), #1382 (issue #1373), #1465 (issue #1434), #1290 (issue #1267), #1441 (issue #1439).

Review capture, selectors, and admission

• Assess. Assess now decodes the native review-assessment/v1 envelope as the v2 contract defines it. It derives closure only from the native candidate.consumed fact for the exact candidate, and it takes the writer profile from the runtime-resolved model and effort. Older envelopes are still accepted.
• Unversioned projects. An unversioned project is prepared for review only after authorized source work, an explicit review, or admission of a valid bounded writer. Children now launch in the same session without a restart.
• Capture routes and profile pins. @decode2 recovers capture routes from fresh native STATUS when volatile route metadata is missing. @egdev6 made native capture honor repository profile pins; a missing role fails closed.
• Committed-range selectors. These now survive intended-untracked selection and a ready plain inspect. Provider tree selectors stay separate from the worktree HEAD anchor, and tracked symlinks are materialized from validated frozen blobs. Native Windows and live Pi lifecycle validation remain incomplete for gentle-ai#2196 and gentle-ai#4924.
• Passive STATUS outside Git. @dnlrsls stopped passive STATUS from running outside Git, so Pi startup no longer initializes a repository unprompted.
• Mounts without private modes. @barbatdev reports mounts that cannot represent private POSIX modes with a dedicated diagnostic instead of chmod 700 advice that cannot take effect. The pinned Gentle AI v4.0.0 adds the matching native typed refusal (upstream #5138).
• Windows owner probes. These now use GENTLE_PI_CANDIDATE_WINDOWS_PROBE_TIMEOUT_MS (default 15 s, maximum 120 s) instead of a fixed 5 s that cold runners exceeded.

Included work: #1584 (issue #1175), #1577 (issue #1567), #1575 (issue #1316), #1546 (issue #1544), #1527 (issues gentle-ai#2196, gentle-ai#4924), #1502 (issue #1501), #1420 (issue #1192), #1488 (issue #656), #1563 (issue #596), #1449 (issue #1446).

Launcher, installer, and harness delivery

• Bridge providers. Under claude-bridge the harness and the open-tasks block never reached the model, because bridge providers forward only structured prompt sections. Both now use appendSystemPrompt.
• Herdr. Isolated interactive launches load the Herdr-managed bridge again, and blocker reporting stays balanced across overlapping questionnaires.
• Codemode warning. Every launch into a Gentle Shell-owned home now excludes Pi 0.99's builtin codemode, which removes the warning while keeping the compact renderer.
• Startup banner. Banner counts follow the active agent directory. The banner shows again under gentle-shell, and also for pi "<prompt>".
• Launcher writes. Atomic writes preserve symlinked settings, and themes and prompts are no longer registered twice.
• Windows install. @barbatdev fixed a postinstall EPERM on read-only Go module-cache files by retrying the cleanup.
• Windows Bash. @decode2 preserved Pi's native Bash tool so its configured shellPath is no longer replaced.

Included work: #1497 (issue #1485), #1561 (issue #1397), #1612 (issue #1611), #1445 (issue #1444), #1381 (issue #1345), #1489 and #1490 (issue #1452), #426 (issue #107).

Shell panels, profiles, and layout

• Narrow screens. Only the selected status bar is shown, and a hidden placement gives back its footer row.
• /gentle:models. The panel uses fullscreen space. Its u action captures the live session model and thinking level; a broader orchestrator-selection feature remains open.
• Profile names. Name input for create, duplicate, and rename is visible. An empty duplicate becomes <name>-copy.
• Usage and status. @egdev6 made Usage include the active profile's providers. @AutanaSoft made the status show the profile in effect for the repository.
• Profile routing. @carlosmoradev accepted effort as an alias for thinking in routing entries, which were silently dropping it.
• Diffs. @carlosmoradev also sanitized tabs and CRLF in diffs of modified files, which were breaking frame borders.
• Overlays. @carolitascl made closing a Gentle overlay repaint every cell, so the screen no longer goes stale after commands.

Included work: #1462 (issue #1425), #1448 (issue #1447), #1522 (issue #1478), #1470 (issue #1469), #1549 (issue #1547), #1423 (issue #1176), #1406 (issue #1403), #1498 (issue #1491), #1404.

Skills, tests, and documentation

• Chained-PR guidance. Obsolete SDD and Strict TDD routing is gone, and chain bases are bound to the verified default branch.
• Skill registry. @carlosmoradev made the registry ignore .atl/ through .atl/.gitignore instead of editing the project's root .gitignore.
• Test runner. @barbatdev made pnpm test run every stage even when an earlier stage fails.
• Test isolation. Tests no longer depend on macOS machine state. @carlosmoradev kept Node 22 timeout fixtures from cancelling later tests.
• Documentation. The README links the demo videos, and the ODD phase work record is closed.

Included work: #1433 (issue #1432), #1417 (issue #1387), #1380 (issue #1285), #1472 (issue #1471), #1496 (issue #1436), #1509, #1451.

Pinned runtime

Gentle AI v4.0.0 (ff77164d) uses module github.com/gentleman-programming/gentle-ai/v4, moving from /v3. Darwin and Linux (amd64 and arm64) use signed release archives with separately pinned archive and extracted-binary digests. Windows uses a Go SumDB-verified source build of that exact tag at the /v4 module path, and the ODD routing mirror's Go imports also point at /v4. The published binary still reports gentle-ai.review-integration/v2 with capabilities/v2.6, and the review provider contract stays at 1.2.0. NATIVE_CLI_CONTRACTS["4.0.0"] adds a row for the new version, and no new capabilities/vN identity is introduced. Upstream, v4.0.0 makes ODD the only workflow, retires SDD and OpenSpec, and moves Pi to its built-in MCP support.

Breaking changes

• Pi 0.99.1 and Node 22.19.0 minimum (#1582). Gentle Shell requires Pi 0.99.1 or later and Node 22.19.0 or later, and Pi host packages are optional peers. Pi 1.0.0 is supported (#1642), but the runtime and peer minimum remains 0.99.1.
• SDD and OpenSpec are retired in Gentle Shell (#1408). The distributed SDD/OpenSpec commands, routes, agents, and packaged resources are removed; ODD is the only development workflow. Native review (RDD) remains, and user-edited or unknown-provenance assets are retained.
• Strict TDD is no longer a separate mode (#1428). Applicable test-first development is the default for behavior changes, and the Strict TDD gate is removed from parent, worker, verifier, and skill guidance.
• Upstream Gentle AI v4.0.0 breaks carried by the pin:
  • The Go module path is now /v4.
  • The sdd-* subcommands and the --sdd-mode and --sdd-profile-strategy flags are removed.
  • sync --strict-tdd is rejected.
  • gentle-ai sync retires pi-mcp-adapter, so Pi MCP servers now rely on Pi's built-in MCP through <Pi agent dir>/mcp.json. Servers in a sibling mcp-adapter.json are migrated. See the Gentle AI v4.0.0 release.
• Behavior changes:
  • Recognized destructive commands always need fresh confirmation in the primary session and are blocked in delegated subagents (#1603).
  • orchestrator_send_message needs interactive consent and a caller-supplied reason, and fails closed in headless runs (#1372).
  • Float is the default card style; an explicitly saved neon preference is kept (#1614).

Upgrade

pi install npm:gentle-pi@4.0.0

Restart Pi, then run gentle-ai sync so the managed orchestrator assets match the pinned runtime. Upgrade Pi to 0.99.1 or later and Node to 22.19.0 or later before installing.

Numbers

257 non-merge commits, 99 merged pull requests, and 12 unique GitHub PR authors since v3.7.0.

Verification

• Local Linux pnpm test with the Gentle AI v4.0.0 binary installed: 4,570 tests, 4,536 passed, 0 failed, 34 Windows-only skips.
• Package verification (verify-package-files) passed, including 69 exact byte-pinned contract artifacts.
• The packed-runner E2E passed against the real published Gentle AI v4.0.0 assets.
• Pin review (#1644): medium risk, review-843de5773266ae8b, approved with three non-blocking advisories and no blocking findings.
• Pi 1.0 tracking (#1642): native review produced no verdict because the reviewer returned empty output twice. The change was delivered on independent verification instead: the full suite had 4,534 passed and 0 failed before rebase, and 635 focused tests passed after rebase.

Install

pi install npm:gentle-pi@4.0.0

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

Full changelog: v3.7.0...v4.0.0