gentle-pi v4.1.0 — Clean-Machine Installers, Bundled Gentle Shell, and Gentle AI v4.1.1

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, #1723, #1728, #1986, #1955, #1832 (issues #1814, #1820), #2006 (issue #2005), #1924 (issue #922), #2003 (issue #2002), #1836 (issue #1834), #1770, #1771, #1772 (issues #1688, #1690), #1773.

Herdr, notifications, and startup

The Herdr Agents sidebar shows active task summaries. A sound and visual warning fires at 90% context, and pending alerts survive active playback. Startup no longer scans home-level repositories, runs the review negotiation after the session starts, and Changes shows the current Git state of the session and its subagent worktrees.

Included work: #1705 (issue #1704), #2080 (issue #2079), #2022 (issue #2021), #2130 (issue #2128).

Gentle AI v4.1.1 pin

See Pinned runtime.

Included work: #2133 (issue #2132).

What was fixed

Setup field reports from the installer

On Windows, pi install npm:gentle-pi exited 1 during setup: recent Windows reports dev 0 from lstat and the volume serial from fstat, so readSettings refused its own settings.json; files are now matched by file index when the path stat has no volume id. On macOS without Homebrew, Gentle AI fell back to brew; the bundled install's pinned Engram is now first on its PATH. The first launch after an installer reinstalled every package because setup never recorded the provisioning marker; it now does. Gentle AI also receives a pi that runs the resolved Pi runtime, pnpm 11.1.1 or newer of any major is accepted, and the pinned Go is used whenever the user's Go cannot be checked.

Included work: #2114 (issues #2105, #2106, #2109), #2117 (issue #2115), #2118 (issue #2116), #2113 (issue #2112).

Installer reliability

The installer reuses pnpm shims it installed itself, standalone native pnpm such as mise's, and pnpm in PNPM_HOME, never downgrades a global-bin pnpm, and uses the verified pnpm when the global one cannot be checked. It pins the Pi gentle-pi runs, acquires the pinned Go before persisting anything, downloads verified archives with the identity encoding, accepts well-formed Windows PATHEXT entries, preserves the Windows environment and Unicode diagnostics, and builds Gentle AI in a short directory on Windows. Missing packed package-manager metadata no longer breaks upgrades, --link resolves to the preserved original Pi home, and transient Windows bundle publication locks are retried.

Included work: #1957, #1961, #1969, #1983 (issue #1978), #1989 (issue #1988), #2032 (issue #2031), #2035 (issue #2033), #2036 (issue #2034), #2044 (issue #2043), #2046 (issue #2045), #2054 (issue #2053), #2064 (issue #2063), #2058 (issue #1972), #2025 (issue #2015), #1184 (issue #946), #2073 (issue #2010).

Native review

The pending consent response no longer has a deadline. START accepts the dangerous_sink and agent_escalation risk reasons, POSIX-quoted apostrophes in consent invocations are split correctly, and the native ABANDON reason is validated. Reviewers inherit the effective Pi transport. Recovery keeps committed-range selectors, audited abandon inputs come from fresh native inventory, terminal escalation and targeted-validator rejection evidence are preserved, and the exact candidate owner filesystem identity is kept. JSON object arguments are accepted without weakening authority, the gentle_review root schema is flat for the Claude Agent SDK, and approved acknowledgement offers an additive next_action.

Included work: #1982 (issue #748), #1929 (issue #1928), #2040 (issue #2039), #2057 (issue #1815), #2052, #1676, #1668 (issue #1159), #1819, #1828 (issue #998), #1739, #1678 (issue #1573), #1710 (issue #1698), #1374 (issue #1371), #1987, #1950.

Safety, agents, providers, and shell

Session work is confined to the project root unless the user consents to an outside path. Explorer children load requested web tools and keep economical exploration with an optional CodeGraph, CodeGraph query and explore are bounded with distinct timeout reports, and the same-clone worktree refusal names the independent-repository exit. Built-in codemode offers a consent-gated opt-out in user-owned homes. NaN exposes exactly each model's efforts with adaptive reasoning aligned to the provider contract, announces an auto-depth session on startup, and deepseek-v4-flash off maps to reasoning_effort none. The skill registry keeps tracked files during refresh and contains watcher errors. Extension shortcuts win over prompt selection keys, Pi's native Working row stays inside Herdr, the dev-binary card owns the startup notice, codemode caches unchanged frames, MCP that stays disabled after migration is reported, and the unit suite no longer inherits the user's environment or profile roles.

Included work: #1520, #2019, #2016, #2027 (issue #1901), #2026 (issue #1915), #1726, #1964 (issue #1963), #1860 (issue #1857), #1968 (issue #1967), #1663 (issue #1645), #1679 (issue #784), #1817 (issue #962), #1947 (issue #1565), #1885 (issue #1884), #1652 (issue #1626), #2061, #2056, #2067 (issue #1838), #1732 (issue #1656), #1727 (issue #1569), #2008, #2123, #1858.

Pinned runtime

Gentle Shell v4.1.0 pins Gentle AI v4.1.1 (github.com/gentleman-programming/gentle-ai/v4, tag commit 898d3976e). Darwin and Linux (amd64 and arm64) install from the signed release archives, verified against both the archive and the extracted binary SHA-256; Windows builds from source through Go's checksum database (h1:+WmZ2IvIOiJ8qtHa7wsjnYKNasem+PByeOZ6HIjoAL8=). v4.1.1 is pinned instead of v4.1.0 because the checksum database recorded v4.1.0 for an earlier tag commit; v4.1.1 is the same code with one consistent checksum. The review provider contract moves from 1.2.0 to 1.3.0 (additive agent lens selection) and is re-mirrored from the published tarball. A new NATIVE_CLI_CONTRACTS row covers 4.1.1; the binary still advertises capabilities/v2.6, so no new capability identity is added.

Breaking changes

None. Existing ODD, review, and package interfaces remain compatible. New release setups install a bundled Gentle Shell; existing global installs keep working and can migrate when you choose.

Upgrade

pi install npm:gentle-pi@4.1.0

Restart Pi, then run gentle-ai sync so the managed orchestrator assets match the pinned runtime.

Numbers

409 non-merge commits, 138 merged pull requests, and 10 unique GitHub PR authors since v4.0.0.

• Release preparation: #2133 (issue #2132).

Verification

• pnpm test on macOS arm64: 6,523 tests, 6,451 passed, 72 Windows-only skips, 0 failed (unit, provider-contract, and runtime-harness stages), re-run by an independent verifier.
• node scripts/verify-package-files.mjs: 209 files, 69 byte-pinned contract artifacts; check:runtime-modules: 15 generated modules match their sources.
• node scripts/test-packed-runner.mjs: packed package E2E passed against the real published Gentle AI v4.1.1 assets.
• Independent verifier re-derived the archive and binary SHA-256 values from fresh downloads, the Windows checksum with empty module caches through both proxy.golang.org and direct origin, and a byte-identical provider-contract mirror.
• Native review was not run for the pin.

Install

pi install npm:gentle-pi@4.1.0

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

Full changelog: v4.0.0...v4.1.0