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

Before submitting

• I searched open and closed issues and found related ones (bug(bundle): bundled Pi pinned to 1.0.0 does not register claude-bridge/claude-haiku-5-5 #2136, feat(launcher): opt into a newer PATH Pi over the adjacent peer, and fix the misleading "Run pi update" notice #2385, 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) but none describing the current v4.4.0 state.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

On a bundled install (Linux, release channel), gentle-shell detected the v4.4.0 release and upgraded Gentle Shell from 4.3.0 to 4.4.0, but Pi stayed at 1.2.0 even though newer Pi releases exist on npm (1.3.0 and 1.4.0). There is no supported way to move Pi forward without waiting for a new Gentle Shell release.

$ gentle-shell --version
gentle-shell 4.4.0
pi 1.2.0
home isolated ~/.gentle-shell/agent

$ npm view @earendil-works/pi-coding-agent versions   # tail
... "1.1.0", "1.2.0", "1.3.0", "1.4.0"

Diagnosis

This is not a failed upgrade; the upgrade did exactly what the bundled design says. Pi is an exact pin per release:

• scripts/installer-preflight.mjs:28 → export const PI_INSTALL_VERSION = "1.2.0"; (still 1.2.0 in the published gentle-pi@4.4.0).
• scripts/build-distribution.mjs writes that value into the version's package.json as an exact dependency, so versions/4.4.0-1.2.0/package.json contains gentle-pi: 4.4.0 and @earendil-works/pi-coding-agent: 1.2.0. The folder name <shell>-<pi> reflects the same pin.
• docs/bundled-install.md ("Exact Pi (S8)") says the launcher runs only the Pi pinned in the version folder and never uses PATH, GENTLE_SHELL_PI, or an adjacent fallback. gentle-shell update for pi/--self/no-target just redirects to gentle-shell upgrade.
• gentle-shell upgrade therefore only changes Pi when a new Gentle Shell release bumps PI_INSTALL_VERSION. 4.4.0 did not.

Net effect for a bundled user: Pi lags the latest Pi by however long it takes to cut the next Gentle Shell release (here two minor versions), the startup banner can still advertise a newer Pi, and neither pi update nor gentle-shell update nor gentle-shell upgrade can fix it.

Expected

Any of the following would resolve the confusion:

1. Bump PI_INSTALL_VERSION in point releases when a compatible Pi is out (peer range is already >=1.2.0), or ship Pi bumps independently of shell features.
2. Provide an opt-in way to upgrade only the pinned Pi in a bundled install (for example gentle-shell upgrade --pi latest, or a documented override), with the same verify-then-switch flow as shell upgrades.
3. At minimum, have gentle-shell upgrade / --version say explicitly that Pi is pinned by the release and which Pi version the next release is expected to carry, so users do not read "pi 1.2.0" after an upgrade as a failure. gentle-shell upgrade printed nothing that explained why Pi was unchanged.

Related

• bug(bundle): bundled Pi pinned to 1.0.0 does not register claude-bridge/claude-haiku-5-5 #2136 — same root cause on the 1.0.0 pin (bundled Pi cannot be moved forward).
• feat(launcher): opt into a newer PATH Pi over the adjacent peer, and fix the misleading "Run pi update" notice #2385 — misleading "Run pi update" notice (also relevant: that notice does not apply to a bundled Pi).
• 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 — Pi 1.4.0 vs AUDITED_PI_EDITOR_VERSIONS (top 1.2.0), which is a likely reason Pi was not bumped; worth tracking together.
• gentle-shell update leaves installation unlaunchable: "global package lacks authenticated metadata" (Pi 1.3.0 → 1.4.0) #2559 / bug(shell): update --extensions-only is documented but Pi 1.4.0 rejects it #2574 — other Pi 1.3/1.4 upgrade problems, which may be why bumping the pin has been deferred.

Environment

• Gentle Shell: 4.4.0 (upgraded from 4.3.0 via gentle-shell upgrade)
• Pi: 1.2.0 (pinned)
• Bundled runtime: Node 24.21.0, pnpm 11.1.1, Engram 3.5.2
• OS: Linux (x86_64, kernel 4.18, RHEL 8-family HPC login node)