Module shells 

The shells installed on this machine, and which one a new local terminal runs: the default-shell setting (docs/specs/SPEC_DEFAULT_SHELL_SETTING_2026_10_13.md).

• list: every shell found, with a name and version, for Settings.
• resolve_for_spawn: the shell a terminal starts with. The block’s own term:localshellpath, else the global setting, else the automatic choice (PowerShell 7, then Windows PowerShell, then Command Prompt on Windows; $SHELL, then /bin/bash elsewhere). A chosen shell that isn’t there falls back to the automatic one, so a stale setting never stops a terminal from opening.

Finding candidates is written over an injected environment and filesystem, with Windows paths handled as strings, like posix_shell::resolve_windows, so the order is tested on every host.

Structs

Candidate 🔒

A shell found, before its version is asked.

SpawnShell

The shell a new local terminal starts with.

Enums

Kind 🔒

Constants

CACHE_TTL 🔒

How long a listing is reused: finding versions runs every shell once.

SEPARATORS 🔒

VERSION_TIMEOUT 🔒

How long a shell may take to say its version before it is listed without one.

Statics

CACHE 🔒

Functions

automatic

The automatic choice, as before the setting was honoured: PowerShell 7 on PATH, else Windows PowerShell, else Command Prompt; elsewhere $SHELL, else /bin/bash.

candidate 🔒

candidates 🔒

dedupe 🔒

Drop repeats: Windows paths compare case-insensitively, and the same file can be reached twice (/bin/bash and /usr/bin/bash on a merged-usr system).

file_name 🔒

A path’s file name, on either separator, so a Windows path reads the same on any host.

for_block

The shell and extra arguments a block’s interactive terminal starts with: resolve_for_spawn on the block’s and the global term:localshellpath, and the block’s term:localshellopts, else the setting’s (appended after the shell-integration arguments). Logs a configured shell that wasn’t found.

installed 🔒

Every shell found, with versions asked in parallel. Reused for CACHE_TTL.

list

What Settings shows: the shells found, the automatic choice, and what a new terminal starts with under global_setting. Blocking: run it off the async runtime.

locate 🔒

A configured shell, as an existing file: a path that exists, or a bare name (pwsh, nu) found on PATH.

real_canonical 🔒

real_env 🔒

real_is_file 🔒

resolve_for_spawn

Which shell a terminal starts with: the block’s term:localshellpath, then the global setting, then automatic.

resolve_with 🔒

shell_opts 🔒

The block’s own term:localshellopts when it has the key, even empty (an agent’s shell pins []), else the setting’s.

unix_candidates 🔒

macOS and Linux candidates: the login shell, then /etc/shells, then Homebrew’s shells that /etc/shells doesn’t list.

version_of 🔒

Ask a shell its version, briefly.

windows_candidates 🔒

Windows candidates, most familiar first: PowerShell 7, Windows PowerShell, Command Prompt, Git Bash, MSYS2 and Cygwin bash, then Nushell and fish on PATH.

with_user_opts

The shell’s arguments: the integration ones and the user’s term:localshellopts. PowerShell’s integration ends -File <script>, and anything after -File goes to the script, so the user’s options go before it; elsewhere they follow (bash wants its long options, --rcfile, first).

wjoin 🔒

base\rel, built as a string: PathBuf::join would use / when the tests run on a Unix host.

wparent 🔒

The folder holding a Windows path, on either separator.