zerogterm 0.2.0-alpha.2 → 0.4.0-alpha.1

package/README.md

@@ -1,21 +1,35 @@
 # ZeroG Terminal
 
-ZeroG Terminal is a Linux-first Electron workspace for persistent `screen` sessions. This first vertical slice includes:
-
-- Electron security boundary: sandboxed renderer, context isolation, disabled Node integration, narrow typed preload API.
-- Session sidebar with create, discover, refresh, and attach actions.
-- Visible actions for opening a persistent local terminal and connecting to an SSH target (`host`, `user@host`, or `user@host:port`).
-- xterm.js terminal renderer and a split workspace surface.
-- Pane close button: closing detaches the session and removes the pane from the workspace; screen-backed sessions stay alive and remain discoverable.
-- Newly opened terminal and SSH panes receive keyboard focus so typing works immediately.
-- Persistent dark/light theme with an accessible sun/moon toggle.
-- Safe session-name validation and argument-array `screen` invocation.
-- AI command approval surface; suggestions are visible and require explicit approval before being sent to the terminal.
-- Voice input per pane: click the microphone, speak, and the utterance is transcribed locally with Whisper-tiny (via Transformers.js; the model is downloaded once on first use) and typed into the pane's prompt without auto-execution.
+ZeroG Terminal is an Electron workspace manager for persistent terminal and SSH sessions on Linux and Windows, with smart features to help keep you productive. It is designed with AI tooling in mind: leave Codex, Claude Code, or other terminal-based agents running in persistent sessions, then return to them without repeating setup and resume commands.
+
+ZeroG Terminal is an alpha project, but it is already useful as a multi-session terminal and SSH workspace. It uses `screen` where available for resumable sessions and falls back to a direct shell PTY when `screen` is not installed.
+
+## Features
+
+- Multi-pane workspaces with stack, vertical split, horizontal split, and four-pane grid layouts.
+- Maximize a focused pane and cycle between sessions without losing the other panes.
+- Local sessions powered by Bash, PowerShell, WSL, and other supported shell backends; persistent sessions use `screen` where available, with a process-only fallback when it is unavailable.
+- SSH sessions for hosts, `user@host`, and `user@host:port` targets.
+- SSH configuration discovery from known connections, including remote `screen` session discovery.
+- Reconnect to existing local or remote `screen` sessions from the Screens view.
+- Remote screen attachment that waits for SSH readiness before sending commands, including host and port-aware matching.
+- Session history for reconnecting to sessions after a relaunch, with bounded structured history and no stored secrets.
+- Workspaces for grouping sessions and quickly switching between projects or tasks.
+- Session overview, collapsible sidebar, keyboard shortcuts, and light/dark themes.
+- xterm.js terminal rendering with scrollback preservation while changing layouts.
+- Local voice input, either with Whisper ONNX inside the app through Transformers.js or through a transcription server on this machine; transcribed text is typed into the selected terminal without automatic execution.
+- A settings panel for appearance, terminal behaviour, session defaults, and speech recognition, including a built-in recognition test.
+- AI command suggestion and approval UI, keeping command execution explicit.
+- Sandboxed Electron renderer, context isolation, disabled Node integration, and a narrow typed preload API.
+- Safe argument-array handling and validation around SSH and `screen` session operations.
+
+The project is particularly useful for terminal-based AI development workflows: start an agent in a persistent session, disconnect or suffer an interrupted connection, and reconnect later to see what it has done and continue working.
+
+See the project walkthrough on [YouTube](https://youtu.be/4aJZCxLHD14).
 
 ## Release status
 
-ZeroG Terminal is currently a public alpha. The initial npm release is `0.1.0-alpha.1` and is configured for the `alpha` dist-tag. The version history is tracked in [versions.txt](versions.txt).
+ZeroG Terminal is currently a public alpha. The current release is `0.3.0-alpha.1`; the version history is tracked in [versions.txt](versions.txt).
 
 The npm package contains the built Electron application and project documentation. It is intended for early adopters and testing rather than production use.
 
@@ -28,8 +42,73 @@ The npm package contains the built Electron application and project documentatio
 - `Ctrl+Shift+T` — new local terminal in the current workspace
 - `Ctrl+Shift+O` — session overview
 - `Ctrl+Shift+B` — toggle sessions sidebar
+- `Ctrl+Shift+,` — settings
 - `Esc` — close overview / dialogs, cancel voice recording
 
+Selecting text with the mouse also copies it, and programs running inside a
+terminal can copy to the system clipboard themselves through the OSC 52 escape
+sequence — this is how TUI tools such as CLI coding agents, tmux and Neovim put
+text on the clipboard, including over SSH. Reading the clipboard through OSC 52
+is refused, so a program on a remote host cannot see what you last copied.
+
+## Settings
+
+Settings open from the gear at the bottom of the left rail, the avatar in the
+title bar, or `Ctrl+Shift+,`. Changes apply immediately and are remembered
+between launches; each page can be reset on its own.
+
+- **Appearance** — theme, terminal font, size, line height and letter spacing,
+  with a live preview. Panes restyle in place and keep their scrollback.
+- **Terminal** — scrollback lines, cursor style and blink, and copy-on-select.
+- **Sessions** — default shell and WSL distribution for new terminals, the
+  layout to start in, and whether the sidebar starts collapsed.
+- **AI & voice** — whether AI suggestions need approval before running, and
+  whether a transcript is typed straight into the pane or shown for review
+  first. Neither option presses Enter for you.
+- **Speech recognition** — engine, model and tuning, described below.
+
+### Speech recognition
+
+Two engines are available.
+
+**Built-in** runs Whisper as ONNX inside the app through Transformers.js, with
+nothing else to install. Choose the model (tiny, base or small; English-only or
+multilingual), the weight precision, and whether to compute on CPU (WASM) or
+GPU (WebGPU) — WebGPU falls back to WASM when it is unavailable. The panel shows
+the download for the chosen combination, from about 41 MB for tiny at q8 to
+about 968 MB for small at full precision; models are cached after first use.
+Multilingual models add language and transcribe/translate options, which
+English-only checkpoints reject and so do not show.
+
+**Local server** posts the recorded audio as a WAV file to a transcription
+server on this machine, using the OpenAI `/v1/audio/transcriptions` shape that
+whisper.cpp's server, LM Studio, faster-whisper-server and similar tools speak.
+This is the way to use a model the built-in engine cannot load — a GGUF build
+such as `unslothai/Qwen3-ASR-0.6B-GGUF` needs a llama.cpp-family runtime, so
+something else has to host it. The URL must be on this machine; a non-loopback
+address is refused rather than sent.
+
+Both engines share the maximum utterance length and the silence threshold, and
+the **Try it** button on that page records a phrase and shows the transcript,
+the recording level and how long transcription took, without typing into a
+terminal. It transcribes even below the silence threshold and says so, which is
+how the threshold gets tuned for a particular microphone.
+
+## Installation and usage
+
+The simplest way to try the published package is through `npx`:
+
+```bash
+npx zerogterm
+```
+
+The package downloads the application and launches it. To use the launcher repeatedly without downloading on each invocation, install it globally:
+
+```bash
+npm install --global zerogterm
+zerogterm
+```
+
 ## Development
 
 ```bash
@@ -40,34 +119,30 @@ npm run build
 npm start
 ```
 
-After installing the published package, launch ZeroG Terminal with:
-
-```bash
-npx zerogterm
-```
+Runtime prerequisites on the host include Node.js and the native build tools required by `node-pty`. Install `screen` as well for persistent, discoverable sessions.
 
-Runtime prerequisites on the host:
+On Fedora/RHEL-like Linux systems:
 
 ```bash
 sudo dnf install screen make gcc-c++ python3
-npm install node-pty
 ```
 
-`node-pty` is required for terminal I/O. When `screen` is installed, local sessions are persistent and discoverable after relaunch. Without `screen`, ZeroG now falls back to a direct `bash` PTY and labels the session as process-only; that shell is lost when the application exits and the dependency warning remains visible. Install `screen` for full persistence:
+On Windows, use a supported Node.js installation and choose PowerShell or WSL when creating a local session. WSL distributions can be selected from the local-session dialog. Remote SSH sessions work independently of the local shell backend.
+
+`node-pty` is required for terminal I/O. When `screen` is installed, local sessions are persistent and discoverable after relaunch. Without `screen`, ZeroG falls back to a direct shell PTY and labels the session as process-only; that shell is lost when the application exits. Install `screen` for full persistence:
 
 ```bash
 sudo dnf install screen
 ```
 
-## Current verification
+## Verification
+
+The current main branch has the following local verification coverage:
 
 - `npm run typecheck`: passes.
-- `npm test`: passes (9 tests covering name validation, `screen -ls` parsing, SSH argument validation, session close semantics, and voice silence detection).
+- `npm test`: passes (28 tests covering remote-screen parsing and prompt readiness, session history, SSH inventory and argument validation, session service behavior, and voice input helpers).
 - `npm run build`: passes and writes `dist/main` plus `dist/renderer`.
-- Electron is configured to disable hardware acceleration by default for the Fedora Toolbox/Wayland runtime; set `ZEROG_ENABLE_GPU=1` only when GPU launch is stable on the host.
-- `npm audit --omit=dev`: reports no known production vulnerabilities.
-
-The live screen + node-pty smoke test creates a temporary named session, writes a marker through the PTY, observes it, and cleans up the session.
+- `npm audit --omit=dev`: production dependency auditing is part of the project quality checks.
 
 ## License
 

package/dist/main/main/clipboard.js

@@ -0,0 +1,30 @@
+// System clipboard writes, verified.
+//
+// Only the main process can reach the OS clipboard, and Electron's writeText
+// returns nothing: when the write loses a race for the clipboard — common on
+// Windows, where a single owner holds it and clipboard-history tools poll it —
+// the renderer has no way to know the text never landed. Reading back turns
+// that silent loss into a retry, and then into a reportable error.
+/**
+ * Did the text land, allowing for line-ending translation?
+ *
+ * Windows stores clipboard text with CRLF line endings, so a multi-line copy
+ * legitimately reads back changed. Comparing raw would report every multi-line
+ * copy as a failure.
+ */
+export function clipboardTextMatches(written, readBack) {
+    return written.replace(/\r\n/g, '\n') === readBack.replace(/\r\n/g, '\n');
+}
+/**
+ * Write text to the clipboard and confirm it is there, retrying once.
+ *
+ * The retry is the useful part: clipboard ownership contention is momentary,
+ * and a second attempt normally succeeds where the first was refused.
+ */
+export function writeClipboardText(clipboard, text) {
+    clipboard.writeText(text);
+    if (clipboardTextMatches(text, clipboard.readText()))
+        return true;
+    clipboard.writeText(text);
+    return clipboardTextMatches(text, clipboard.readText());
+}

package/dist/main/main/main.js

@@ -1,7 +1,9 @@
 import { app, BrowserWindow, clipboard, ipcMain, Menu, session } from 'electron';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ScreenService, discoverShellBackends, parseWslDistributions } from './session-service.js';
+import { writeClipboardText } from './clipboard.js';
+import { ScreenService, parseWslDistributions } from './session-service.js';
+import { discoverShellBackends } from './shell-catalog.js';
 import { SessionHistoryStore, defaultHistoryPath } from './session-history.js';
 import { buildRemoteScreenAttachArgs, buildRemoteScreenDiscoveryArgs, listKnownConnections, parseRemoteScreenList, validateKnownConnection } from './ssh-inventory.js';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -128,7 +130,11 @@ ipcMain.on('terminal:resize', (_event, sessionId, cols, rows) => {
 ipcMain.handle('clipboard:writeText', (_event, text) => {
     if (typeof text !== 'string')
         throw new Error('clipboard:writeText requires a string');
-    clipboard.writeText(text);
+    // Reject rather than resolve on a lost write: the renderer shows the message
+    // in the status bar, so the user is not told text was copied when it was not.
+    if (!writeClipboardText(clipboard, text)) {
+        throw new Error('Clipboard write failed — another application is holding the clipboard');
+    }
 });
 ipcMain.handle('clipboard:readText', () => clipboard.readText());
 ipcMain.handle('ai:suggest', () => ({

package/dist/main/main/session-service.js

@@ -3,11 +3,17 @@ import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
+import { defaultShellBackend, isLocalShellBackend, resolveShellBackend } from './shell-catalog.js';
 const execFileAsync = promisify(execFile);
 const require = createRequire(import.meta.url);
 const NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,48}$/;
-/** host, user@host, host:port, user@host:port — no shell metacharacters. */
-const SSH_TARGET = /^(?:([A-Za-z0-9._-]+)@)?([A-Za-z0-9.-]+)(?::(\d{1,5}))?$/;
+/**
+ * host, user@host, host:port, user@host:port — no shell metacharacters.
+ * Host and user must start alphanumeric: a leading '-' would be parsed by
+ * ssh's getopt as an option, and `-Fsome.cfg` can point ssh at an attacker
+ * -chosen config file (hence ProxyCommand) without any shell involvement.
+ */
+const SSH_TARGET = /^(?:([A-Za-z0-9][A-Za-z0-9._-]*)@)?([A-Za-z0-9][A-Za-z0-9.-]*)(?::(\d{1,5}))?$/;
 export function validateSessionName(name) {
     const value = name.trim();
     if (!NAME.test(value)) {
@@ -32,37 +38,14 @@ export function validateSshTarget(input) {
     const args = ['-tt'];
     if (portText)
         args.push('-p', portText);
-    args.push(destination);
+    // '--' ends option parsing, so the destination can never be read as a flag.
+    args.push('--', destination);
     return { target: value, args };
 }
 export function parseWslDistributions(output) {
     return output.split(/\r?\n/).slice(1).map((line) => line.replace(/^\*?\s*/, '').trim())
         .map((line) => line.split(/\s{2,}/)[0]).filter((name) => /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(name));
 }
-export function shellBackendArgs(backend, distribution) {
-    if (backend === 'wsl') {
-        if (distribution && !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(distribution.trim()))
-            throw new Error('Invalid WSL distribution name.');
-        return { backend, executable: process.platform === 'win32' ? 'wsl.exe' : 'wsl', args: distribution ? ['-d', distribution.trim()] : [], label: distribution ? `WSL · ${distribution.trim()}` : 'WSL', wslDistribution: distribution?.trim() };
-    }
-    if (backend === 'powershell')
-        return { backend, executable: process.platform === 'win32' ? 'pwsh.exe' : 'pwsh', args: [], label: 'PowerShell' };
-    if (backend === 'zsh')
-        return { backend, executable: 'zsh', args: [], label: 'zsh' };
-    return { backend: 'bash', executable: 'bash', args: [], label: 'bash' };
-}
-export async function discoverShellBackends() {
-    const result = [shellBackendArgs('bash')];
-    for (const backend of ['powershell', 'wsl']) {
-        const candidate = shellBackendArgs(backend);
-        try {
-            await execFileAsync(candidate.executable, backend === 'wsl' ? ['--status'] : ['-NoProfile', '-Command', '$PSVersionTable.PSVersion.ToString()']);
-            result.push(candidate);
-        }
-        catch { /* unavailable */ }
-    }
-    return result;
-}
 export function parseScreenList(output) {
     return output
         .split('\n')
@@ -104,7 +87,12 @@ export class ScreenService {
     sshSessions = new Map();
     fallbackLocalSessions = new Map();
     onEvent;
-    constructor(options = {}) { this.onEvent = options.onEvent; }
+    /** Injectable so tests can exercise routing and teardown without a real shell. */
+    spawnPty;
+    constructor(options = {}) {
+        this.onEvent = options.onEvent;
+        this.spawnPty = options.spawnPty ?? ((file, args, ptyOptions) => loadPty().spawn(file, args, ptyOptions));
+    }
     async available() {
         try {
             await execFileAsync('screen', ['--version']);
@@ -148,11 +136,15 @@ export class ScreenService {
     async createLocal(nameOrRequest, cwd = homedir()) {
         const request = typeof nameOrRequest === 'string' ? { name: nameOrRequest, cwd } : nameOrRequest;
         const safeName = validateSessionName(request.name);
-        const backend = request.backend ?? 'bash';
-        const shell = shellBackendArgs(backend, request.wslDistribution);
+        // No backend named means "whatever this machine prefers": a native shell
+        // on Windows, the login shell or bash on Unix. resolveShellBackend throws by
+        // name when a named backend is not installed, so a missing shell is a clear
+        // message rather than a pty that dies on spawn.
+        const shell = request.backend
+            ? resolveShellBackend(request.backend, request.wslDistribution)
+            : defaultShellBackend();
+        const backend = shell.backend;
         const requestedCwd = request.cwd ?? homedir();
-        if (backend !== 'bash' && !(await executableAvailable(shell.executable)))
-            throw new Error(`${shell.label} is not installed or unavailable.`);
         if (!(await this.available())) {
             const fallback = { id: `local:${safeName}`, name: safeName, kind: 'local', host: 'local', cwd: requestedCwd, status: 'detached', lastSeen: new Date().toISOString(), persistence: 'process', backend, scope: 'local', source: 'active', wslDistribution: shell.wslDistribution };
             this.fallbackLocalSessions.set(fallback.id, fallback);
@@ -193,12 +185,16 @@ export class ScreenService {
             if (fallback) {
                 fallback.status = 'connected';
                 fallback.lastSeen = new Date().toISOString();
-                const shell = shellBackendArgs(fallback.backend ?? 'bash', fallback.wslDistribution);
+                const shell = isLocalShellBackend(fallback.backend)
+                    ? resolveShellBackend(fallback.backend, fallback.wslDistribution)
+                    : defaultShellBackend();
                 this.spawnCommand(id, shell.executable, shell.args, onData, onExit, fallback.cwd);
                 this.onEvent?.('attached', fallback, true);
                 return { ...fallback };
             }
-            const name = id.slice('local:'.length);
+            // Session ids cross the IPC boundary from the renderer, so re-validate
+            // rather than trusting that createLocal produced this one.
+            const name = validateSessionName(id.slice('local:'.length));
             this.spawnCommand(id, 'screen', ['-x', name], onData, onExit);
             this.onEvent?.('attached', existing, true);
             return { ...existing, status: 'connected', persistence: 'screen' };
@@ -226,7 +222,7 @@ export class ScreenService {
             const fallback = this.fallbackLocalSessions.get(id);
             if (fallback)
                 return fallback;
-            const name = id.slice('local:'.length);
+            const name = validateSessionName(id.slice('local:'.length));
             return {
                 id,
                 name,
@@ -244,8 +240,7 @@ export class ScreenService {
         return session;
     }
     spawnCommand(sessionId, file, args, onData, onExit, cwd = homedir()) {
-        const pty = loadPty();
-        const proc = pty.spawn(file, args, {
+        const proc = this.spawnPty(file, args, {
             name: 'xterm-256color',
             cols: 120,
             rows: 32,
@@ -310,10 +305,3 @@ export class ScreenService {
         this.onEvent?.('closed', session, false);
     }
 }
-async function executableAvailable(executable) { try {
-    await execFileAsync(executable, ['--version']);
-    return true;
-}
-catch {
-    return false;
-} }

package/dist/main/main/shell-catalog.js

@@ -0,0 +1,193 @@
+// Which shells this machine can actually start, and what to spawn for each.
+//
+// Ported forward from the cross-platform discovery work in 690f01d on
+// fix/cross-platform-and-review-fixes, which never reached dev. What shipped
+// instead knew only `pwsh.exe`, so a Windows machine without PowerShell 7 — the
+// common case, since 7 is a separate install — was offered no PowerShell at
+// all, and the two shells Windows always has, Windows PowerShell and Command
+// Prompt, could not be chosen. bash was offered unconditionally on every
+// platform, including where it cannot start.
+//
+// Candidates are resolved against PATH rather than probed by spawning them.
+// Spawning was slow and wrong in two ways: it cold-started PowerShell on CI,
+// which intermittently blew vitest's timeout, and it made `--version` the test
+// of existence, which Command Prompt does not answer. Resolving also yields an
+// absolute path, which is what node-pty needs on Windows — it does not apply
+// PATHEXT, so a bare `bash` fails there with "File not found:".
+import { statSync } from 'node:fs';
+/** Distro names reach `wsl.exe -d <name>`; a leading '-' would read as a flag. */
+const WSL_DISTRIBUTION = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/;
+const LOCAL_SHELL_BACKENDS = [
+    'bash', 'zsh', 'fish', 'sh', 'powershell', 'pwsh', 'cmd', 'wsl'
+];
+/**
+ * Does this value name a shell?
+ *
+ * A stored session's backend can also be a transport — 'screen' for a session
+ * inside screen, 'ssh' for a remote one — and it arrives from the history file
+ * on disk, so it is narrowed rather than asserted.
+ */
+export function isLocalShellBackend(value) {
+    return typeof value === 'string' && LOCAL_SHELL_BACKENDS.includes(value);
+}
+function defaultIsFile(candidate) {
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function resolved(options) {
+    const platform = options.platform ?? process.platform;
+    return {
+        platform,
+        windows: platform === 'win32',
+        path: options.path ?? process.env.PATH ?? '',
+        pathExt: options.pathExt ?? process.env.PATHEXT ?? '.EXE;.CMD;.BAT;.COM',
+        loginShell: options.loginShell ?? process.env.SHELL,
+        isFile: options.isFile ?? defaultIsFile
+    };
+}
+/**
+ * Path arithmetic for the *target* platform, not the host.
+ *
+ * node:path's `delimiter`, `sep` and `join` follow whichever platform this code
+ * is running on, which is right in production and wrong for reasoning about a
+ * platform passed in — splitting a Unix PATH on ';' yields one long entry that
+ * matches nothing. Doing it explicitly keeps the module honest either way.
+ */
+function pathParts(value, windows) {
+    return value.split(windows ? ';' : ':').filter(Boolean);
+}
+function joinPath(directory, name, windows) {
+    const separator = windows ? '\\' : '/';
+    const trimmed = directory.replace(/[\\/]+$/, '');
+    return `${trimmed}${separator}${name}`;
+}
+function fileName(value) {
+    return value.split(/[\\/]/).pop() ?? value;
+}
+/**
+ * Resolve a bare command name against PATH without spawning anything.
+ *
+ * On Windows the extension is usually part of the command already, but PATHEXT
+ * is honoured so `pwsh` finds `pwsh.exe` — the empty extension is tried first so
+ * an exact name still wins.
+ *
+ * `accept` lets a caller reject a match and keep searching later PATH entries,
+ * which is what finding Git Bash behind System32's shim requires.
+ */
+export function findExecutable(command, options = {}, accept = () => true) {
+    const { windows, path, pathExt, isFile } = resolved(options);
+    const extensions = windows ? ['', ...pathExt.split(';').filter(Boolean)] : [''];
+    for (const directory of pathParts(path, windows)) {
+        for (const extension of extensions) {
+            const candidate = joinPath(directory, command + extension, windows);
+            if (isFile(candidate) && accept(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Is this the `bash.exe` shim Windows installs for WSL?
+ *
+ * System32's bash.exe is present on every Windows 10 and 11 machine whether or
+ * not a distribution is installed, and it launches WSL rather than Git Bash.
+ * Offering it would mean a "Git Bash" entry that starts something else, or
+ * nothing at all — and WSL already has its own backend. Rejecting it as a
+ * candidate rather than abandoning the search lets Git for Windows' own
+ * bash.exe, further along PATH, still be found.
+ */
+function isWslBashShim(file) {
+    return /[\\/]windows[\\/]system32[\\/]/i.test(file);
+}
+/** The shells worth offering on this platform, in the order they are preferred. */
+function shellCandidates(windows) {
+    if (windows) {
+        return [
+            { backend: 'powershell', label: 'Windows PowerShell', command: 'powershell.exe' },
+            { backend: 'pwsh', label: 'PowerShell 7', command: 'pwsh.exe' },
+            { backend: 'cmd', label: 'Command Prompt', command: 'cmd.exe' },
+            { backend: 'wsl', label: 'WSL', command: 'wsl.exe' },
+            // Git for Windows ships bash; useful, but not a login shell for the OS.
+            { backend: 'bash', label: 'Git Bash', command: 'bash.exe' }
+        ];
+    }
+    return [
+        { backend: 'bash', label: 'Bash', command: 'bash' },
+        { backend: 'zsh', label: 'Zsh', command: 'zsh' },
+        { backend: 'fish', label: 'Fish', command: 'fish' },
+        { backend: 'sh', label: 'sh', command: 'sh' }
+    ];
+}
+/**
+ * Move the user's login shell to the front, and say so in its label.
+ *
+ * $SHELL is what the user chose for themselves, so it belongs first — but only
+ * as an ordering: a login shell that is not one of the known backends is left
+ * alone rather than spawned under a name the rest of the app cannot describe.
+ */
+function preferLoginShell(shells, loginShell) {
+    if (!loginShell)
+        return shells;
+    const name = fileName(loginShell);
+    const index = shells.findIndex((shell) => shell.backend === name);
+    if (index <= 0)
+        return shells;
+    const preferred = { ...shells[index], label: `${shells[index].label} (login shell)` };
+    return [preferred, ...shells.filter((_, position) => position !== index)];
+}
+/**
+ * Every shell that exists on this machine, most preferred first.
+ *
+ * The first entry is the platform default: a native shell on Windows, the login
+ * shell or bash on Unix.
+ */
+export function discoverShellBackends(options = {}) {
+    const context = resolved(options);
+    const found = [];
+    for (const candidate of shellCandidates(context.windows)) {
+        const skipShim = context.windows && candidate.backend === 'bash';
+        const file = findExecutable(candidate.command, options, skipShim ? (match) => !isWslBashShim(match) : undefined);
+        if (!file)
+            continue;
+        found.push({
+            backend: candidate.backend,
+            executable: file,
+            args: candidate.args ?? [],
+            label: candidate.label
+        });
+    }
+    return context.windows ? found : preferLoginShell(found, context.loginShell);
+}
+/** The backend a new session gets when the caller names none. */
+export function defaultShellBackend(options = {}) {
+    const shells = discoverShellBackends(options);
+    if (!shells.length)
+        throw new Error('No usable shell was found on PATH.');
+    return shells[0];
+}
+/**
+ * What to spawn for a requested backend.
+ *
+ * The backend name crosses the IPC boundary from the renderer, so it is looked
+ * up in the catalogue rather than treated as a command: the renderer can name a
+ * shell, never an executable. A backend that is not installed fails here, by
+ * name, instead of as a pty that dies on spawn.
+ */
+export function resolveShellBackend(backend, distribution, options = {}) {
+    const match = discoverShellBackends(options).find((shell) => shell.backend === backend);
+    if (!match) {
+        const label = shellCandidates(resolved(options).windows).find((candidate) => candidate.backend === backend)?.label ?? backend;
+        throw new Error(`${label} is not installed or unavailable.`);
+    }
+    if (backend !== 'wsl' || !distribution)
+        return match;
+    const trimmed = distribution.trim();
+    if (!WSL_DISTRIBUTION.test(trimmed)) {
+        throw new Error('WSL distribution names may contain letters, numbers, spaces, _, ., and - only.');
+    }
+    return { ...match, args: ['-d', trimmed], label: `WSL · ${trimmed}`, wslDistribution: trimmed };
+}

package/dist/main/main/ssh-inventory.js

@@ -2,7 +2,10 @@ import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const HOST = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,253}$/;
-const USER = /^[A-Za-z0-9._-]{1,64}$/;
+// Must start alphanumeric like TOKEN/HOST above: the user is concatenated into
+// `user@host`, so a leading '-' makes the whole destination look like an option
+// to ssh's getopt (`-Fevil.cfg@host` reads an attacker-chosen config file).
+const USER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const SCREEN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,48}$/;
 function words(value) {
     const result = [];