[Alan-TheGentleman]

Linked Issue

Refs #5738

PR Type

• type:bug — Bug fix (non-breaking change that fixes an issue)

Summary

On Linux amd64, switching an installed Separate target from Stable to Main preview in Manage and running "Update now" failed with global provision refused: Main composition extra member, and every retry then failed with occupied path.

Root cause:

• The overlay verified with verify-main-sdk-composition after materializing the runtime. scripts/provision-gentle-shell-private-global.mjs does not list that action in mainRuntimeActions, so it rejects the native .gentle-ai member as an extra member.
• Neither the unwind nor the Main -> Stable cleanup removed the runtime/node_modules symlink that materialize-main-sdk-runtime creates.
• The seam-only unit tests replaced both steps, which is why CI never saw it.

Changes

File	Change
internal/shellinstaller/user_main_bindings_unix.go	Shared userMaterializeMainSDK helper, used by the fresh Main install and the overlay. One userMainSDKSelectedAction constant.
internal/shellinstaller/user_channel_overlay_unix.go	The overlay materializes through the shared helper and verifies with verify-main-sdk-selected, like a fresh Main install. The gate, the unwind and the cleanup share one Main path list, which includes runtime/node_modules.
internal/shellinstaller/user_main_overlay_actions_unix_test.go	New. Parses the provision script's action lists and emulates their real on-disk effects and refusals, so the field failure reproduces in tests.
internal/shellinstaller/user_channel_overlay_unix_test.go	Tagged linux && amd64. Round-trip and rollback-then-retry tests use the real actions.

Size exception

716 changed lines (578 added / 138 removed). Most of it is test code: the action-contract emulator (user_main_overlay_actions_unix_test.go) that reproduces the field failure against the real provision script action lists, plus the round-trip and rollback tests. The product change is about 150 lines. The emulator and the fix have to land together, because without the emulator the defect is invisible to CI again.

Test Plan

• RED: TestUserUnixOverlayComposeMatchesFreshMainActions failed with the field message global provision refused: Main composition extra member. TestUserUnixOverlayStableToMainUnwindsCompletely failed with overlay residue survived the unwind: runtime/node_modules.
• GREEN: both pass. go test -count=1 ./internal/shellinstaller/... is ok natively on darwin.
• CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go vet ./internal/shellinstaller/... and go test -c: ok. The Linux-only overlay tests run in this PR's CI.
• Real-host proof (scenario D of shell-tui-acceptance.yml on ubuntu-latest) follows once the registry fix lands, because scenario D reuses scenario A's verification.

Known limit: installs that already carry the leftover runtime/node_modules from the old bug get an explicit already occupied refusal. No auto-repair is included.

Contributor Checklist

• PR is linked to an issue with status:approved
• Commit follows conventional commits
• No Co-Authored-By trailers

Summary by CodeRabbit

• Bug Fixes
  • Improved switching between Stable and Main installations on Linux, including handling of runtime dependencies and existing files.
  • If a switch fails during setup or verification, staged changes are rolled back and settings are restored, allowing the switch to be retried.
  • Main installation paths are now cleaned up consistently after a successful switch, while occupied paths are left unchanged when a switch is refused.

[coderabbitai]

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: fc05e09c-442a-4210-9741-98fa76ae7251

Commits

Reviewing files that changed from the base of the PR and between 05c3abb and 36c9532.

Files selected for processing: 1

• internal/shellinstaller/user_channel_overlay_unix_test.go

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

Walkthrough

The Unix channel overlay now shares Main SDK materialization and selected-SDK verification actions. It tracks runtime/node_modules with the other Main paths for occupancy checks, rollback, and cleanup during Stable/Main transitions.

Changes: Unix channel overlay

Layer / File(s)	Summary
Main SDK actions and composition internal/shellinstaller/user_main_bindings_unix.go, internal/shellinstaller/user_main_overlay_actions_unix_test.go	Main SDK composition and installed-SDK verification use the userMainSDKAction boundary. Tests compare overlay composition actions with fresh Main installation actions and exercise rollback after selection or manifest-rebind failures.
Overlay staging, cleanup, and rollback internal/shellinstaller/user_channel_overlay_unix.go, internal/shellinstaller/user_channel_overlay_unix_test.go	Stable-to-Main staging checks all tracked Main paths and registers shared rollback cleanup. Main-to-Stable cleanup removes those paths after commit. Tests cover occupied paths, repeated channel switches, rollback, and retry.

Priority: Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Possibly related issues

• Gentleman-Programming/gentle-ai#5738 — Records the Stable-to-Main verification failure and retry obstruction from an occupied runtime/node_modules path addressed by these changes.

Possibly related PRs

• Gentleman-Programming/gentle-ai#5719 — Adds the Unix channel-only overlay that this PR extends with shared Main materialization, verification, and cleanup.
• Gentleman-Programming/gentle-ai#5695 — Implements in-place Stable/Main SDK switching for Windows; this PR implements related overlay behavior for Linux amd64 Unix installations.
• Gentleman-Programming/gentle-ai#5743 — Adds the LauncherNote result field used by the Unix overlay result construction.

Suggested labels: type:fix

Suggested reviewers: decode2

Merge Risk: Minimal · up to 36c95

No current-head merge-blocking risk was established; the documented refusal for pre-existing residue remains a known limitation.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 76.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 25 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main changes: fresh Main-install verification for the Unix channel overlay and complete unwind behavior.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

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

• X
• Mastodon
• Reddit
• LinkedIn

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