gentle-pi v3.0.0 — Gentle Shell, Organic by Default
gentle-pi v3.0.0 renames the product to Gentle Shell in the startup logo and sidebar, and makes Organic Driven Development (ODD) the always-on default workflow: every request now runs through a mandatory Authorize, Explore, Resolve uncertainty, Classify, Track, Implement, Close protocol, with a single recoverable feature document (odd/tasks/<feature>.md plus its Engram mirror) and configured TDD instead of test-presence guessing. This is a major version because three refactor(sdd)! changes remove previously supported SDD surface: the standalone sdd-sync phase, ordinary attempt governance (acquire/settle/reconcile), and sdd-research's artifact and persistence machinery. Alongside the workflow change, this release adds a curated command palette on alt+k and /gentle:commands, an opt-in agent-model profile pin scoped to one repository with a one-key update from /gentle:models, a unified sidebar Status frame with animated working feedback, and a large Windows agent transport, IPC and startup hardening effort.
Provenance
- Previous stable:
v2.7.0→c2bad51139608bd2590c889a34578e84f7a81a43 - Release target:
v3.0.0→c49ff7b975ba7b2151b65d1c289e7aefa9ce6173(version bump and publish-workflow fix on top of62dd3f65) - CI workflow: run 35104452315 on the release-target commit. On the preceding feature head
62dd3f65,review-repository-windowsfailed once on a Windows runner flake (candidate owner preparation) and succeeded on rerun of the same commit. - Pinned Gentle AI:
v2.9.1(unchanged). Gentle AI v3.0.0 is cut from the/v2Go module without a path migration, so its Windows source build is not installable; gentle-pi keeps packaging v2.9.1 until the/v3module release. The review provider contract is1.2.0on both, so native review keeps working.
What's new
The product is now Gentle Shell
The startup banner replaces the Gentle-Pi wordmark with a compact, slanted Gentle Shell script, and the centered sidebar title is renamed to match. Artwork shape, kerning, shadows and responsive rendering are covered by regressions.
Included work: #1105.
Organic Driven Development is the mandatory default protocol
The full seven-step ODD protocol (Authorize, Explore, Resolve uncertainty, Classify, Track before the first write, Implement task by task, Close) now renders in the always-on harness prompt, ahead of the orchestrator instructions, so it runs on every request without asking about workflow or tasks. SDD/OpenSpec remains available but only when explicitly selected. Work is tracked as one feature document with a full Engram recovery mirror, and TDD mode is resolved from existing configuration or explicit user choice rather than inferred from test presence.
Included work: #1080, #1037, #1067.
Curated command palette on alt+k and /gentle:commands
alt+k or /gentle:commands opens a grouped, searchable menu of Gentle commands (Configuration, Session, Diagnostics, SDD, Skills) with human labels, live descriptions used for search, and configured shortcut hints. Only commands that are actually registered are listed, and selecting one runs it exactly as if the slash command had been typed. GENTLE_PI_COMMANDS_KEY rebinds the shortcut, and off disables it, since ctrl+p and ctrl+k are reserved by Pi.
Included work: #1102.
Agent-model profile pinned to one repository
/gentle:profiles gains an opt-in per-repository pin: p toggles a clone-local pin, P toggles a committable repository declaration, so a repository can use one named profile independently of the globally active one. The pin resolves at the same point subagent routing already resolves, so a pinned repository writes no global models.json, subagents.json, agent frontmatter, or orchestrator setting. Unpinned repositories keep today's behavior, and an unreadable, stale, or out-of-worktree pin degrades to it, reported rather than silently applied.
Included work: #1075.
Update the current profile from /gentle:models
The u key on /gentle:models saves the global routing exactly like ctrl+s, then snapshots the routing just saved, plus the orchestrator setting, into the current profile: the pinned profile when a pin wins, otherwise the globally active one. The panel now shows Current profile: <name> and names the target across two footer rows.
Included work: #1100.
Unified sidebar status and working feedback
Project, Changes, Usage and Integrations now live inside one sidebar Status frame. Gentle editor ownership is preserved while pi-pretty is active, the shell working… label animates at Pi's 80ms cadence alongside the existing flower spinner, and the redundant live Thinking… row above the input is hidden while historical transcript markers stay intact.
Included work: #1110.
Windows agent transport, IPC and startup hardening
A large, sequential effort adds bounded active-orchestrator notifications with host-only identity, discovery and send tools over POSIX Unix sockets and Windows named pipes. Windows uses a current-account-SID boundary and a fixed PowerShell 5.1 helper without elevation, separates Windows helper startup (30s default/cap) from subsequent RPCs (2s cap), and fixes FD3/IPC cleanup and POSIX post-close replacement handling. The change is a 20-file, roughly 8,800-changed-line integration reviewed and merged as a single approved size exception.
Included work: #799.
Breaking changes
Three refactor(sdd)! changes intentionally remove previously supported SDD behavior. They were integrated into main together as a single tracker.
Research is optional and output-only
sdd-research no longer accepts a research_artifact input and no longer reads or writes repository or Engram artifacts directly. The child returns findings inline; the parent supplies context and questions at launch and owns any authorized persistence and readback. Partial findings or unavailable sources no longer block a proposal. Existing historical research artifacts are not deleted or rewritten.
Included work: #1061.
Ordinary attempt governance is retired
Attempt acquisition, settlement, reconciliation, persisted live attempt state, and the subagent_reconcile consumer are removed, because the classical native provider already retired the commands they depended on. Native identity/selection, human edit consent, exact tool restrictions, and readable historical records are preserved; ordinary task completion was never treated as verification PASS and still is not.
Included work: #1058.
Standalone sync is retired in favor of unified native continuation
sdd-sync is no longer a supported phase. Registered consumers now follow native readiness instead of a duplicate local status authority, and stale sync execution is refused rather than silently routed. Package-owned managed sync assets are removed only when ownership hashes prove they are package-managed; modified user copies are left untouched. The classical flow becomes apply through archive under the native provider's own continuation, without a post-SDD RDD step.
Included work: #1056.
These three children, plus companion fixes for the same tracker, were folded into main together as the final integration.
Included work: #1073.
Upgrade now
pi install npm:gentle-pi@3.0.0Restart Pi, then run:
gentle-ai syncThe package-local Gentle AI runtime stays at v2.9.1 and is reinstalled by the package postinstall; run gentle-ai sync afterwards so managed agent and reviewer assets match it. If a repository relied on the retired standalone sdd-sync phase, use the native provider's own continuation and archive instead; do not delete or overwrite a modified local copy as an upgrade shortcut.
What was fixed
Safer pi-pretty extension loading
The pi-pretty extension used a compiled-runtime-incompatible createRequire() package-root load, which could pad model-visible tool results with phantom spaces. Loading is now a cached ESM import performed after quiet-tool suppression is configured, and @heyhuynhgiabuu/pi-pretty is upgraded from 0.6.14 to 0.6.27.
Included work: #1108.
RPC input preflight no longer consumes delegated prompts
The natural-language SDD input hook called the parent-only preflight resolver for every matching prompt regardless of mode. In RPC mode that resolver rejects by design, and the hook's try/catch converted the rejection into { action: "handled" }, so a delegated child ACKed a prompt it never ran: zero turns, zero tool calls, surfacing only later as an inactivity timeout. The hook now returns continue for ctx.mode === "rpc" before calling the resolver; the parent still resolves and persists preflight as before. First shipped in v2.6.0, present through v2.7.0.
Included work: #1036.
The stall watchdog no longer times out live work
The watchdog could not tell a healthy child running a long foreground command from a hung one, because it re-armed only on parsed RPC objects and a tool call records its last step only when announced; a silent command could be stopped as timed out while it was still working. An announced tool call in flight now counts as live work under its own tool_stall_timeout_ms ceiling (default 30 minutes, floored at the existing silence budget), and the watchdog also stops re-arming on fire-and-forget UI traffic, such as periodic setStatus or notify calls, that normalizes to no task events. The stop message now names the tool that was still running when its ceiling was reached.
Missing first run event now names the model
A successful RPC prompt response only proves prompt acceptance, not provider or model admission. A silent child previously ended with generic wording ("stalled ... after: prompt accepted"), obscuring where it actually stopped. A prompt-accepted idle timeout with no run event now names the selected or resolved model and the missing first-event boundary, without claiming provider rejection where there is no evidence for it.
Included work: #1094.
Effective agent-model routing precedence fixed
Subagent launch already resolved model and thinking effort independently, per field, preferring subagents.json model profiles, then agent frontmatter, then defaults. /gentle:profiles instead returned any non-empty profile entry wholesale, so a profile that only overrode effort could hide the frontmatter model that launch still used. The panel now merges materialized profile and frontmatter routing per field, matching what launch actually applies.
Included work: #1088.
Profile snapshots stay in place
Saving a profile snapshot with s previously tore the panel down and rebuilt it, causing visible flicker, and gave no durable confirmation that a saved profile does not change live routing. Snapshot operations now stay inside the existing panel, refresh counts through a typed row-update API, and show outcome-first inline feedback.
Included work: #1030.
Background subagent work rejected in print mode
Pi's pi -p print mode is single-shot: it prints the parent response and disposes the session. A background subagent_run or subagent_continue previously returned a task ID immediately even though no live parent remained to receive its later result. Both calls are now rejected at the shared launch boundary before runner admission, task allocation, child spawn, or history write; bounded print-mode task execution and TUI/RPC background completion are unaffected.
Included work: #1097.
Duplicate transcript measurement render removed
The sidebar wrapper's intrinsic-height measurement pass was rendering the transcript a second time. The measurement pass now renders an empty subtree instead, and the native layout subtree is unchanged; this fixes duplicate rendering only and does not change the sidebar's remaining presence-poll/native-composition behavior tracked separately.
Included work: #1098.
Capture-limit notice shown once and surfaced in Changes
Once the session-change capture cap (256 records or 4 MiB of snapshots) was reached, every later write or edit re-emitted the limit notice, flooding the shell with repeated toasts, and the Changes widget gave no persistent hint that capture was capped. The notice is now delivered once through SessionChanges.takeNotice() and rendered as a persistent "capture limit reached" hint in the footer widget, the Changes card, and the overlay summary.
Included work: #1096.
Card tone applied to the complete frame
The card state tone previously painted only the title and left rail of a frame. It now paints every frame segment, while muted subtitle, dim hint, body text, width, and truncation semantics are preserved.
Included work: #1106.
npm publish workflow follows the repository rename
The trusted npm publish workflow still gated on github.repository == 'Gentleman-Programming/gentle-pi' and required package.json.repository to name the old repository, so after the rename to gentle-shell every dispatch was skipped. The guard, the expected repository URL, and package.json.repository now name Gentleman-Programming/gentle-shell, which is also what npm provenance verifies against the workflow's source repository. The npm package name stays gentle-pi.
Included work: c49ff7b9 on main.
Numbers
87 non-merge commits, 29 merged pull requests, and 3 unique GitHub PR authors since v2.7.0.
Install
pi install npm:gentle-pi@3.0.0Package: https://www.npmjs.com/package/gentle-pi
Full changelog: v2.7.0...v3.0.0