bug(install): preserve explicit regular TUI mode during global installs

[dnlrsls]

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

Current main includes the install-time settings change introduced by #739. A successful postinstall in a recognized global Pi-managed npm installation writes "tuiMode": "fullscreen" even when the user explicitly selected "regular". The documented behavior also reasserts fullscreen on later recognized postinstall runs.

Pi 0.85.1 still marks fullscreen as experimental. In that mode, an ordinary mouse-wheel event moves one logical row; regular mode delegates scrolling to the terminal's faster native scrollback. The mismatch is tracked upstream in earendil-works/pi#9052.

As a result, installing or updating Gentle Pi can override an explicit user preference and place users back on a known slower scrolling path. The resulting regression is easy to attribute incorrectly to the whole Gentle Pi release.

Steps to reproduce

1. Use a Gentle Pi build from main after feat(shell): add responsive sidebar and global fullscreen setup #739 in the recognized global Pi-managed npm package location.
2. Set Pi's global tuiMode to regular, for example through /settings.
3. Run the successful Gentle Pi postinstall again through a recognized global install or update.
4. Inspect the global Pi settings and observe that tuiMode is now fullscreen.
5. Start Pi 0.85.1 in Windows Terminal and scroll through a transcript with the wheel.
6. Compare with pi --tui-mode regular: fullscreen moves one row per ordinary event unless Alt is held, while regular mode uses the faster native scrollback.

Expected and actual behavior

Expected: A Gentle Pi install or update preserves an explicit tuiMode: regular selection. Fullscreen remains opt-in while the upstream scroll-rate mismatch is unresolved. An explicit tuiMode: fullscreen selection also remains untouched.

Actual: The recognized global postinstall replaces or reasserts tuiMode: fullscreen. A later install can therefore undo the user's switch back to regular and restore the slower wheel behavior.

gentle-pi version

main@4728187c4f64b44fd407c3e83563b0afd1d0fece (behavior introduced by #739; not present in the v2.5.0 tag)

Pi version

0.85.1

Operating system

Windows

Relevant logs or error output (optional)

Gentle Pi change: #739
Upstream scroll tracker: earendil-works/pi#9052
Pi fullscreen default wheel step: 1 logical row per event
Pi fullscreen Alt-wheel multiplier: 5x
Documented installer behavior: a later recognized postinstall can reset regular to fullscreen

[WarisGG]

Reproduced on current main (12de3e98).

With a recognized global npm install and settings.json = {"tuiMode":"regular","theme":"rose"}, installTuiModeSetting(...) returns { changed: true, recognized: true } and rewrites the file to { "tuiMode": "fullscreen", "theme": "rose" }. An explicit tuiMode: "regular" is silently replaced; every other field is preserved.

Cause. In scripts/install-tui-mode-setting.mjs, the only early return is if (original.value.tuiMode === "fullscreen"). Every other value, including an explicit user regular, falls through to the unconditional { ...original.value, tuiMode: "fullscreen" }. The writer cannot tell "no preference yet" from "user chose regular".

This reverses behavior currently pinned by tests. #739 introduced persist-fullscreen on purpose and the suite encodes it. Tests that would move to the new contract:

• tests/install-tui-mode-setting.test.ts: recognized global npm and Pi Git installation persists fullscreen and preserves other settings
• tests/install-tui-mode-setting.test.ts: creates or resets fullscreen: { "tuiMode": "regular", ... }
• tests/install-tui-mode-setting.test.ts: waiting installer rereads another cooperative writer's settings

Fresh-home bootstrap tests (installIsolatedTuiModeSetting, isolated-run bootstrap) still pass: a home with no tuiMode still gets fullscreen.

Minimal change. Apply fullscreen only when the tuiMode key is absent, and treat any explicit value as user intent. The sidebar already degrades below 140 columns in regular/narrow modes (#739), so an explicit regular host stays coherent.

Proportionality. This is a deliberate product-behavior change, not a silent bug fix, so I am asking first. Per the issue-first policy I have not touched production code. Can a maintainer confirm whether preserving an explicit regular selection is the wanted contract, and add status:approved if so? If fullscreen must stay authoritative on recognized global installs, I would rather this be closed as by-design than submit a change you would reject.

---

Disclosure: the reproduction and analysis were produced with material AI assistance (el Gentleman harness on Pi; provider nan, model deepseek-v4-flash) and verified against main by the human contributor.

[WarisGG]

Duplicate pair, flagging before this gets implemented twice.

The same defect already has an issue with an implementation attached:

• Recognized global postinstall resets an explicit tuiMode:"regular" back to fullscreen on every update #1017 (2026-09-14, @barckcode): same defect, same file, same early return.
• PR fix(install): preserve an explicit tuiMode instead of resetting it to fullscreen #1018 (@barckcode): installTuiModeSetting short-circuits on any defined tuiMode instead of only "fullscreen", with updated tests/install-tui-mode-setting.test.ts coverage. +48/-17 across 4 files.

State today:

Item	State
#1017 labels	none, so PR #1018 cannot satisfy "Check Issue Has status:approved"
PR #1018	open, not draft, no CI checks, no review, last update 2026-09-14T15:03
PR #1018 base	7df2f2fb, 525 commits behind main (12de3e98)
Target files	scripts/install-tui-mode-setting.mjs and its test changed on main after that base (2867ac32, 5577a5d2, 77eb617e)

I re-checked main: the early return is still if (original.value.tuiMode === "fullscreen"), and 2867ac32 only added a call-site isPiManagedInstall guard. The overwrite is unchanged and the defect is live.

So the same fix has one issue carrying the bug label (#763, this one) and one carrying an implementation (#1017 + #1018). Closing the other as a duplicate would let approval land in one place.

I will stand down if @barckcode is still on it, in which case #1018 likely wants a rebase onto current main. If it is considered stale, I can prepare a fresh slice from main against whichever issue stays open.