bug(upgrade): a bug in the main-channel upgrade path cannot be fixed through that path #2356

Before submitting

• I searched open and closed issues and did not find a report of this problem.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

A bug in the main-channel upgrade path cannot be fixed through that path. gentle-shell upgrade --channel main runs entirely with the Gentle Shell that is already installed: runUpgrade (scripts/main-channel.mjs) builds and verifies Gentle AI with the installed buildMainGentleAi, and only afterwards packs and installs the new Shell:

if (!aiCurrent) await buildMainGentleAi({ ... });   // installed (old) code
if (!shellCurrent) {
  const tgz = await packMainShell({ ... });          // installed (old) code
  await installGlobal(manager, tgz, run);
}

So when buildMainGentleAi, packMainShell or installGlobal has a bug, an affected install never reaches the Shell that fixes it. #2301 is the live case: #2340 is merged, but an install from before it keeps failing while gentle-ai main is exactly the v4.2.0 commit, and only an unrelated event (the next untagged gentle-ai commit, or a release) unblocks it. The wizard has the same shape: its runner is the one bundled with the downloaded installer.

Possible directions:

• Fail forward (smallest change): when the Gentle AI step fails, still pack and install the main Shell, do not record the main channel, and exit non-zero naming gentle-shell upgrade --channel main as the retry. The retry then runs the new Shell's code. Cost: the user is briefly on the main Shell with the previous Gentle AI (the pinned binary or the previously registered main build, which fix(main-channel): accept a Gentle AI main commit that is a release tag #2340 now preserves).
• Shell first, then delegate: install the main Shell first, then run the Gentle AI step through the newly installed gentle-shell, so every verification always runs the newest code. More robust, but it needs a re-exec and a recorded intermediate state.

Either way the Gentle AI verification stays fail-closed; the change is only which code performs it.

Steps to reproduce

Isolated sandbox (separate HOME, PNPM_HOME, npm prefix and caches), macOS, Go 1.26.2, pnpm 11.1.1, with gentle-ai main at 4acaf4241bea (v4.2.0):

1. pnpm add -g gentle-pi@4.3.0 --allow-build=gentle-pi (released before fix(main-channel): accept a Gentle AI main commit that is a release tag #2340).
2. gentle-shell upgrade --channel main.

Expected and actual behavior

Expected: the upgrade reaches the current main Shell, whose fixed verification accepts the tagged commit.

Actual:

$ gentle-shell upgrade --channel main
gentle-shell upgrade: main-gentle-ai-unverified: the built Gentle AI does not report commit 4acaf4241bea
[exit 1]

No channel is recorded and nothing is installed, so every retry fails the same way.

gentle-pi version

4.3.0 (reproduction); fix target is main after abc4b27

Pi version

Not involved (upgrade path only)

Operating system

macOS

Relevant logs or error output (optional)

See the output under Expected and actual behavior. Related: #2301, #2340.