fix(bundled): reach the newest Pi, install the music player on request, and fix the profiles screen by Alan-TheGentleman · Pull Request #2599 · Gentleman-Programming/gentle-shell

Alan-TheGentleman · 2026-10-27T23:51:45Z

Linked Issue

PR Type

Bug fix

Summary

Pins the bundled Pi to 1.4.0 after auditing every private Pi surface Gentle Shell relies on (the Vim editor's editor.js, undo-stack.js and keys.js are byte-identical in 1.2.0, 1.3.0 and 1.4.0; cli/args.js and the extension types are identical; package-manager-cli.js and tui-alt-screen.js changes are compatible).
Adds gentle-shell update --latest for bundled installs: the newest published stable Pi, installed after a warning without the release's verified lockfile, verified and activated like upgrade, with rollback. Neither upgrade nor --latest ever downgrades Pi.
/gentle:music in a bundled install offers, with consent, to install the gentle-stream player inside Gentle Shell: a pinned, sha256-verified uv 0.13.6 plus the uv-managed Python 3.13 and gentle-stream from a pinned GitHub archive (no git), all under the Gentle Shell prefix.
/gentle:profiles is now the only entry to the models and profiles screen (/gentle:models is retired; its routing file verbs become /gentle:profiles export-routing|restore-routing), and switching profile tabs no longer flickers (the panel switches in place instead of closing and reopening its overlay).

Changes

Commit	Change
`3cf1c20d8`	Pin bundled Pi 1.4.0; admit audited Pi 1.3.0/1.4.0 editors; lockfile resolves Pi 1.4.0
`697d2e4b6`	`gentle-shell update --latest` (`scripts/bundled-install.mjs`, `lib/gentle-shell-bundled.ts`, `bin/gentle-shell.mjs`, help, docs)
`536277e3c`	Retire `/gentle:models`, move its verbs, fix the profile tab flicker (`extensions/gentle-ai.ts`, palette, docs)
`685c4b8e7`	`/gentle:music` opt-in player install (`scripts/installer-downloads.mjs`, `scripts/bundled-install.mjs`, `extensions/gentle-music.ts`, docs)
`ebf11fb6e`	Downgrade guard for `--latest`, verification follow-ups
`9abed718e`	Music player check shared with the installer; drop inherited `PYTHON`/`PIP_`
(docs)	`odd/tasks/bundled-pi-latest.md` feature record

Test Plan

pnpm test (macOS arm64, Node 24): 7760 tests, 7649 pass, 36 fail, 75 skipped. Every failure is pre-existing in the local environment: the same suite on origin/main (b577f39) gives 7622 pass and 38 fail in the same files (agent-home, gentle-agents, orchestrator-scope, notification-audio-native, notification-pulse-client, notification-pulse-stream, plus notification-customize on main). provider-contract and runtime-harness stages pass. pnpm run typecheck: 0 diagnostics.
Focused suites per commit, observed RED before GREEN for each new rule.
Independent verification of 697d2e4b6: S1/S3 PASS, 0 blockers; 6175 update inputs without --latest produce identical plans before and after.
Independent verification of 685c4b8e7 + ebf11fb6e: S3/S5 PASS, 0 blockers; uv pins re-hashed; archive extraction rejects traversal and links; a corrupted download publishes nothing; the uv environment is confined to the prefix; nothing installs without consent; the non-bundled hint is byte-identical. Its two hardening advisories are fixed in 9abed718e.
Real macOS arm64 end-to-end of the music install in a scratch prefix: pinned uv acquired and verified, gentle-stream installed, gentle-stream --help exit 0, second run idempotent.

Size

size:exception: the maintainer chose one PR for this release (Pi pin, --latest, music install, profiles fixes).

Contributor Checklist

Summary by CodeRabbit

New Features
- Bundled installations can use gentle-shell update --latest to install the newest published Pi, with a warning that some features may be unavailable. Later upgrades won’t downgrade that Pi.
- Gentle Music can offer to install its player in bundled installations when no player is available.
- The models and profiles panel now combines both views, with tabs that switch in place. Routing export and restore are available as profile commands.
- Vim editor support now covers audited Pi versions 1.3.0 and 1.4.0.
Changes
- /gentle:models has been removed; use /gentle:profiles for models and profiles.

…editors

…ished Pi A bundled install could only reach the Pi its Gentle Shell release pins. 'update --latest' (also pi|self|--self|--all forms) resolves the newest stable Pi with the bundled pnpm, installs it beside the active version without the release lockfile after a warning, and activates it through the same launcher check and rollback as 'upgrade'. A plain upgrade never downgrades that Pi for the same Gentle Shell version. Docs list the audited Pi 1.3.0/1.4.0 editors.

…p the tab flicker /gentle:models opened the same screen as /gentle:profiles, so it is retired: its routing file verbs move to '/gentle:profiles export-routing' and 'restore-routing' (they move the global routing, not a profile), and the command palette lists one 'Models and profiles' entry. Switching profile tabs closed the overlay and reopened it after awaiting the model catalog, painting the screen below for a frame. The panel now switches profiles in place through a switcher callback, saving first when asked.

…ed Gentle Shell /gentle:music in a bundled install without gentle-stream, uvx or uv now asks to install the player instead of pointing at manual steps. On consent it fetches a pinned, sha256-verified uv 0.13.6 into runtime/ and installs the uv-managed Python 3.13 and gentle-stream from a pinned GitHub archive (no git) under music/, isolated from any user uv, Python or virtualenv settings. A pnpm or npm install keeps the existing hint.

When the latest dist-tag names a Pi older than the active one, --latest now changes nothing instead of installing it. The install test pins the --no-frozen-lockfile flag, the installVersion comment no longer claims pnpm writes no lockfile, and the reference documents --latest outside a bundled install.

…on and pip settings The /gentle:music extension now accepts the prefix player only when it resolves to a regular file inside music/, the same rule the installer uses, and the player's uv no longer inherits any PYTHON* or PIP_* variable.

coderabbitai · 2026-10-27T23:52:11Z

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: Repository UI
Review profile: ASSERTIVE
Plan: Advanced
Run ID: b45ea29f-122e-4194-ba14-ebb59f0d2622

Commits

Reviewing files that changed from the base of the PR and between b577f39 and e33ce57.

Files ignored due to path filters: 1

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml, !pnpm-lock.yaml

Files selected for processing: 30

README.md
bin/gentle-shell.mjs
docs/gentle-music.md
docs/gentle-shell.md
docs/readme-reference.md
extensions/gentle-ai.ts
extensions/gentle-music.ts
lib/command-palette-catalog.ts
lib/gentle-shell-bundled.ts
lib/gentle-shell-launcher.ts
lib/vim-editor-adapter.ts
odd/tasks/bundled-pi-latest.md
runtime/gentle-shell-bundled.mjs
runtime/gentle-shell-launcher.mjs
scripts/bundled-install.mjs
scripts/installer-downloads.mjs
scripts/installer-preflight.mjs
scripts/pi-update.mjs
tests/bundled-install.test.ts
tests/command-palette.test.ts
tests/gentle-ai.test.ts
tests/gentle-music.test.ts
tests/gentle-shell-bundled.test.ts
tests/gentle-shell-launcher.test.ts
tests/gentle-shell.test.ts
tests/installer-downloads.test.ts
tests/model-profiles-preservation.test.ts
tests/pi-update.test.ts
tests/runtime-harness.mjs
tests/vim-editor-adapter.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Walkthrough

This change adds an opt-in latest-Pi update for bundled installs, a consent-based bundled Gentle Music player installation, and a unified /gentle:profiles screen with routing subcommands and in-place profile switching. It also updates the bundled Pi pin, editor audit list, tests, and documentation.

Changes: Bundled Pi updates

Layer / File(s)	Summary
Latest-Pi update routing `lib/gentle-shell-bundled.ts`, `runtime/gentle-shell-bundled.mjs`, `bin/gentle-shell.mjs`, `scripts/pi-update.mjs`, `lib/gentle-shell-launcher.ts`, `runtime/gentle-shell-launcher.mjs`, `tests/gentle-shell-bundled.test.ts`, `tests/pi-update.test.ts`, `tests/gentle-shell-launcher.test.ts`, `README.md`, `docs/gentle-shell.md`, `docs/readme-reference.md`, `odd/tasks/bundled-pi-latest.md`	Bundled update planning recognizes `--latest` for Pi self-updates and preserves extension-update arguments. The CLI routes the request to the bundled installer. Documentation describes the option and its behavior.
Install and activate the published Pi version `scripts/bundled-install.mjs`, `tests/bundled-install.test.ts`	The installer accepts stable published Pi versions, performs unverified installation without the release lockfile, verifies the result, and activates it. It leaves the active version unchanged when the published version is not newer.
Update the Pi pin and editor audit `scripts/installer-preflight.mjs`, `lib/vim-editor-adapter.ts`, `tests/vim-editor-adapter.test.ts`, `docs/gentle-shell.md`, `docs/readme-reference.md`	The Pi pin and editor adapter allowlist include version 1.4.0. The audited editor versions include 1.3.0 and 1.4.0.

Bundled Gentle Music installation

Layer / File(s)	Summary
Pin and verify the bundled uv runtime `scripts/installer-downloads.mjs`, `scripts/bundled-install.mjs`, `tests/installer-downloads.test.ts`, `tests/bundled-install.test.ts`	The installer pins uv 0.13.6 for supported platforms, validates its archive and version, and places its runtime paths inside the bundle.
Install and resolve the bundled player `extensions/gentle-music.ts`, `scripts/bundled-install.mjs`, `tests/gentle-music.test.ts`, `tests/bundled-install.test.ts`, `docs/gentle-music.md`, `docs/gentle-shell.md`	Gentle Music checks PATH, the bundled player, uvx, and uv. When no player is available in a bundled install, it can offer installation. The installer validates the player, retries without samples when needed, and reports installation progress and results.

Unified models and profiles screen

Layer / File(s)	Summary
Consolidate the screen and routing commands `extensions/gentle-ai.ts`, `lib/command-palette-catalog.ts`, `tests/gentle-ai.test.ts`, `tests/command-palette.test.ts`, `tests/gentle-shell.test.ts`, `tests/runtime-harness.mjs`, `tests/model-profiles-preservation.test.ts`, `README.md`, `docs/readme-reference.md`	`/gentle:profiles` replaces `/gentle:models` as the models-and-profiles screen. Routing export and restore use `export-routing` and `restore-routing` subcommands.
Switch profiles in place `extensions/gentle-ai.ts`, `tests/gentle-ai.test.ts`, `docs/readme-reference.md`	The open screen switches profiles in place. It can save or discard the current draft, and a failed save leaves the current profile and its edits displayed.

Priority: Normal

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  actor User
  participant GentleMusic
  participant BundledInstaller
  participant uv
  participant GentleStream
  User->>GentleMusic: Request music playback
  GentleMusic->>BundledInstaller: Check bundled player
  GentleMusic->>User: Offer installation when no player is found
  User->>GentleMusic: Accept installation
  GentleMusic->>BundledInstaller: Install player and report progress
  BundledInstaller->>uv: Install Gentle Stream with managed Python
  uv-->>BundledInstaller: Provide installed player
  BundledInstaller-->>GentleMusic: Return player path and samples status
  GentleMusic->>GentleStream: Start playback

Possibly related issues

bug(bundle): upgrading 4.3.0 → 4.4.0 leaves bundled Pi at 1.2.0 while Pi 1.4.0 is available; no way to update Pi #2593 — Reports that bundled Pi cannot advance to a newer published version; this change adds a latest-Pi update path.
bug(bundle): bundled Pi pinned to 1.0.0 does not register claude-bridge/claude-haiku-5-5 #2136 — Connects the bundled Pi pin to unavailable model registration; this change updates the pin and adds an opt-in newer-Pi path.
gentle-shell update leaves installation unlaunchable: "global package lacks authenticated metadata" (Pi 1.3.0 → 1.4.0) #2559 — Concerns update verification failures; this change tests that failed verification preserves the active version and removes the new version.
bug(vim): Pi 1.4.0 bundles pi-tui 1.4.0, outside AUDITED_PI_EDITOR_VERSIONS (top 1.2.0) — Gentle Vim degrades to ordinary editing #2449 — Reports that Pi 1.4.0 is blocked by the editor audit; this change adds 1.4.0 to the audited versions.
feat(models): one models screen with profiles as tabs for /gentle:models and /gentle:profiles #2586 — Requests one profile-based models screen and routing operations; this change consolidates the command and moves routing operations.
bug(models): /gentle:models does not reflect a session-bound profile applied with Enter in /gentle:profiles #2451 — Reports inconsistent routing display between models and profile panels; this change makes /gentle:profiles the unified screen.

Possibly related PRs

Gentleman-Programming/gentle-shell#2496 — Defines the existing Gentle Stream lookup flow that this change extends with a bundled-player option.
Gentleman-Programming/gentle-shell#2588 — Changes the same models and profiles command surface and panel behavior.
Gentleman-Programming/gentle-shell#2493 — Changes the profile panel code and tests that this change consolidates into one screen.

Suggested labels: type:feature

Suggested reviewers: decode2, danielgap

Merge Risk: Minimal · up to e33ce

No actionable issue remains from this review; the change is mergeable after normal checks.

Pre-merge checks: 3 · 1 · 1

Failed checks: 1 warning · 1 inconclusive

Check name	Status	Explanation	Resolution
Out of Scope Changes check		The PR also retires `/gentle:models`, moves routing commands to `/gentle:profiles`, and changes profile-tab rendering. These changes affect the profiles UI and command surface. Issue `#2598` only covers…	Remove the profiles command, routing, and tab-switching changes from this PR, or link an active issue that directly requires those coding changes.
Docstring Coverage		Docstring coverage is 65.71% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surv…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 3 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely summarizes the three main changes: bundled Pi updates, opt-in music-player installation, and the profiles-screen fix.
Linked Issues check		Issue `#2598` has three coding objectives. The PR pins bundled Pi to 1.4.0, adds the explicit bundled `update --latest` path, verifies and activates the result with rollback, and prevents downgrades. It…

Full details: Linked Issues check

Explanation

Issue #2598 has three coding objectives. The PR pins bundled Pi to 1.4.0, adds the explicit bundled update --latest path, verifies and activates the result with rollback, and prevents downgrades. It adds consent-based /gentle:music installation with pinned and SHA-256-verified uv, uv-managed Python 3.13, and a pinned archive under the Gentle Shell prefix. Focused tests and the reported macOS end-to-end test cover these behaviors. The ignored pnpm-lock.yaml is not used as evidence of absence.

Full details: Out of Scope Changes check

Explanation

The PR also retires /gentle:models, moves routing commands to /gentle:profiles, and changes profile-tab rendering. These changes affect the profiles UI and command surface. Issue #2598 only covers bundled Pi updates and /gentle:music installation. The profile changes have no stated connection to either objective, even though the current PR description includes them.

Resolution

Remove the profiles command, routing, and tab-switching changes from this PR, or link an active issue that directly requires those coding changes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 65.71% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 35 functions across 24 files. (6 skipped: 5 unsupported, 1 too large.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 1

📝 Generate docstrings: 💡

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Alan-TheGentleman added 7 commits October 28, 2026 00:30

feat(runtime): pin bundled Pi 1.4.0 and admit audited Pi 1.3.0/1.4.0 …

3cf1c20

…editors

docs(odd): record the bundled Pi latest feature

e33ce57

Alan-TheGentleman added type:bug Bug fix size:exception labels Oct 27, 2026

Alan-TheGentleman merged commit 8375e0b into main Oct 28, 2026
9 checks passed

coderabbitai Bot mentioned this pull request Oct 28, 2026

fix(profiles): mark the profile this session launches with on the routing screen #2604

Open

This was referenced Oct 28, 2026

fix(music): say /gentle:music is not available on native Windows #2612

Merged

bug(bundle): upgrading 4.3.0 → 4.4.0 leaves bundled Pi at 1.2.0 while Pi 1.4.0 is available; no way to update Pi #2593

Closed

Navigation Menu

Repository navigation

fix(bundled): reach the newest Pi, install the music player on request, and fix the profiles screen - #2599

fix(bundled): reach the newest Pi, install the music player on request, and fix the profiles screen#2599
Alan-TheGentleman merged 7 commits into
mainfrom
fix/bundled-pi-latest

Alan-TheGentleman commented Oct 27, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading

Sequence Diagram(s)

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Alan-TheGentleman commented Oct 27, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked Issue

PR Type

Summary

Changes

Test Plan

Size

Contributor Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Sequence Diagram(s)

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Alan-TheGentleman commented Oct 27, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 27, 2026 •

edited

Loading