feat(launcher): named environments with per-env Gentle configuration #2235

Before submitting

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

Problem or opportunity

Gentle Shell can already run against a separate agent home (--isolated, --home <path>, --link), but there is no way to keep several of them and pick one. Each separate home means typing its path every time. You cannot see what a home holds (sign-ins, packages, setup state), and the active home is not visible inside a session. Anyone who separates work, personal and client setups, or experiments with configuration without touching their main one, ends up with ad-hoc aliases and no overview.

On top of that, Gentle's own configuration (~/.pi/gentle-ai: model routing and /gentle:profiles, persona, /gentle:customize, permissions and guardrails) is always shared across every home. So two homes cannot have, for example, different model profiles.

Proposed outcome

Named environments, managed by the launcher and fully compatible with today's homes:

• gentle-shell --env <name> opens a session in a managed home under ~/.gentle-shell/envs/<name>/ (root overridable with GENTLE_SHELL_ENVS_DIR). It is exclusive with --link, --isolated and --home, and never creates an unknown env, so a typo fails instead of making an empty home. An env auto-provisions on first launch like any new home.
• gentle-shell envs opens a full-screen manager in Gentle's visual identity (rose, ✿ Gentle Shell, rounded cards, ❯ selection). It can list, create, rename, delete (after typing the name), open, set the default, run setup, install a package, and check sign-ins. A detail card shows the path, setup record, sessions, signed-in provider ids (never credentials), packages, and config scope. envs list and envs new <name> cover scripts and no-TTY use.
• The install's own home stays first-class. The manager lists it as Gentle Shell base (the --isolated home). Opening it is --isolated, and making it the default persists "home": "isolated", exactly like gentle-shell home isolated. The default is shown as name (default), like the /gentle:profiles markers, and follows the existing precedence (flag, then persisted home, then --isolated).
• The active env is visible in the session: env <name> right after the brand in the header, and an Env group above Project in the Status card. The launcher passes the name only for named envs and clears any inherited value.
• Per-env Gentle configuration, like VS Code profiles. For each category (models = routing + profiles, persona, appearance, behavior), an env either shares the base configuration live or owns a copy in <env>/gentle-ai/. A category that becomes own is seeded once, copied from the base home or another env, or started empty. This is available in the manager's create form, with c on an existing env, and as envs new/config <name> --own/--share <list|all> [--from <env> | --empty]. Install-level files (update channel, dev binary) and repository settings stay shared. Envs without a scope file share everything, which is today's behavior.
• Bundled (standalone) installs: works the same, using the bundled Pi. Both self-uninstall variants list ~/.gentle-shell/envs as "your named envs" under Not touched, and refuse any plan that would remove something inside it.

Out of scope for now: per-env Engram memory, which stays shared.

Alternatives considered

• Shell aliases around --home <path>: no overview, no visible active home, no shared-vs-own configuration, and every path is typed by hand.
• Exporting GENTLE_PI_CONFIG_HOME per home: it moves the whole configuration at once, and in a bundled install the prefix's config takes precedence, so it cannot express "own profiles, shared appearance".
• Symlinking config files per env: fragile, because several writers rename over files and would silently replace the links.

Additional context

• The implementation is split into chained PRs. Each one targets main and builds on the PR before it:
  1. feat(launcher): named envs with --env and envs list|new #2257, core: --env, envs list|new, the session indicator, and uninstall protection.
  2. feat(launcher): full-screen envs manager with the base home #2258, gate: the envs manager and the base home.
  3. feat(launcher): per-env Gentle configuration, like VS Code profiles #2259, config: per-env Gentle configuration.
  • Separate: feat(installer): show Gentle AI download progress on a terminal #2255 shows Gentle AI download progress on a terminal (found while setting up envs).
• The work is test-first: launcher, manager reducer and renderer, config scope (including a drift guard that every config-home read names its category), and bin and bundled-prefix integration. The manager is driven through a simulated TTY, as the bundled startup-offer test does.
• An independent verification pass found three issues, and all are fixed: history capture ignored the env's behavior scope, the drift guard missed subfolders, and scope changes followed symlinks. On the full local suite there are no new failures compared with main.
• Verified on a real macOS standalone install from the v4.2.0 installer: an env owning models shows its own profile while the base home keeps the shared one. Not yet verified on Windows.
• Related: bug(history): prompt history store and transcript bootstrap ignore the active agent home and always use ~/.pi/agent #1618 (prompt history ignores the active agent home, so history would still mix across envs), feat(sessions): explain isolated history and offer opt-in same-project cross-home discovery #2014 (isolated history across homes), feat(profiles): support session-bound active profiles without global routing mutation #1064 (session-bound profiles), feat(launcher): mark externally verified homes without nested setup #1383 (externally verified homes).