feat(terminal): select installed shell for new sessions

[eranknafo2001]

Problem

The integrated terminal follows the environment shell without giving users an explicit choice, and the settings UI cannot tell which supported shells are actually installed on the connected machine.

Changes

• add an environment-scoped terminal shell setting with System default, Zsh, Bash, and Fish
• probe the connected environment's PATH for installed shells and publish those capabilities in server config
• filter the settings dropdown to installed shells while preserving an unavailable prior selection as disabled
• resolve the setting at spawn time so new and restarted terminals use the latest choice across web, desktop, and mobile clients
• retain fallback shell behavior when the selected executable cannot start

Validation

• 133 focused contract, terminal manager, settings, and client-runtime tests
• focused WebSocket handshake integration test
• contracts, client-runtime, server, and web typechecks
• targeted lint, formatting, and diff checks

This is a draft because the settings UI has not yet received a manual browser pass or screenshots.

Implemented with GPT-5.6 Codex in T3 Code through the Codex harness.

Note

Add terminal shell selection to settings with per-platform shell discovery

• Adds a terminalShell preference to ServerSettings and ServerSettingsPatch with forward-compatible decoding that defaults to "system".
• Extends TerminalManager with resolveAvailableShells, which probes installed shells (including fish) and returns the available ones.
• Includes availableTerminalShells in the serverGetConfig RPC response so the client knows which shells are installed.
• Adds a Terminal Shell selector to the General settings panel in SettingsPanels.tsx, showing only installed shells and marking unavailable selections.
• Adds terminal shell as a searchable settings item routing to /settings/general.

^{Macroscope summarized be9a495.}

---

Note

Medium Risk
Changes PTY spawn behavior and server config RPC; mistakes could break terminals or misreport installed shells, though existing fallback spawn logic is retained.

Overview
Adds an environment-scoped terminal shell preference (system, zsh, bash, fish) and wires it through contracts, server spawn logic, and the web Settings → General UI.

Server: TerminalManager reads terminalShell from server settings when opening or restarting PTYs (with fallback to the system shell if settings read fails). It exposes resolveAvailableShells() by probing PATH for installed shells; fish is included in spawn fallbacks. serverGetConfig returns availableTerminalShells alongside editors, with both discoveries sharing a renamed 5s timeout helper so config does not block indefinitely.

Web: General settings shows a shell selector built from installed shells; a previously selected shell that is no longer installed stays visible but disabled. Reset/search/dirty-state handling and user docs for the terminal setting are included.

^{Reviewed by Cursor Bugbot for commit be9a495. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b611925d-d8ec-4515-b558-1931d8267d0b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[macroscopeapp]

One convention finding: a renamed helper keeps a back-compat alias instead of updating its only consumer.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 2cd84f9aed032118c55780b445687738fcc2c4a4. Configure here.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new user-facing feature for selecting terminal shells, with changes spanning UI, server-side configuration, and runtime terminal spawning behavior. New features that modify how terminals are opened warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}