gentle-pi v4.3.0 — Runtime-Enforced Orchestration, Session Scratch, and Gentle AI v4.2.0

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 gentle-pi@4.3.0 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 (issue #2029), #2192, #2203 (issue #2191).

Still open: whether ps -o lstart= stays fixed across clock steps on every BSD has not been checked on a real macOS or BSD host; Linux uses /proc start ticks.

Pinned runtime

Gentle Shell v4.3.0 pins gentle-ai v4.2.0 (github.com/gentleman-programming/gentle-ai/v4, tag commit 4acaf4241beae1e0c977c92dfe406a270f8d40de). Darwin and Linux installs use the published signed archives for amd64 and arm64, verified by archive and extracted-binary SHA-256. Windows builds from source, verified against the Go checksum database entry h1:J8EluS7QrfM+m3vmQlF26B/shZRjD6rBfsKtrABL5mc=. The review provider contract moves from 1.3.0 to 1.4.0, which adds the routing/pi.md routing block. The binary still advertises capabilities/v2.6, so the new 4.2.0 NATIVE_CLI_CONTRACTS row repeats 4.1.1 and no new capability identity is added.

Breaking changes

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

Upgrade

pi install npm:gentle-pi@4.3.0

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

Numbers

110 non-merge commits, 41 merged pull requests, and 6 unique GitHub PR authors since v4.2.0.

Verification

• Local suite on Linux (Node, pnpm test): unit tests 7018 total, 6946 pass, 0 fail, 72 skipped (Windows-host checks); provider-contract and runtime-harness stages pass.
• node scripts/verify-package-files.mjs: 215 required files and 69 exact byte-pinned contract artifacts for the v4.2.0 runtime.
• npm pack --dry-run: gentle-pi 4.3.0, 902 files, 11.4 MB.
• node scripts/test-packed-runner.mjs: packed package E2E passed against the published Gentle AI v4.2.0 assets (gentle-pi 4.3.0; Gentle AI 4.2.0).
• Gentle AI v4.2.0 pin: an independent verifier recomputed all eight archive and binary digests from the published assets and matched checksums.txt.
• Native review: #2318 high risk, lineages review-e6f96fb8f1a7b6c5 and review-17762a93afa13f60 approved with advisory findings only; #2300 lineage review-26c64c03b81311bb approved; #2321 assessed medium with no review due.
• Bench: six headless x6 runs on a339dca7 had no delivery-question stops and were all accepted in the first round (39/39 acceptance, 20/20 regression).

Install

pi install npm:gentle-pi@4.3.0

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

Full changelog: v4.2.0...v4.3.0