zerogterm 0.3.0-alpha.1 → 0.5.0-alpha.1

package/README.md

@@ -1,21 +1,37 @@
 # 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.
+- Draggable dividers between panes and beside the sidebar, so a split does not have to be an even one. Sizes are remembered between launches.
+- 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 per-pane proceed button that sends a configurable phrase — `OK, proceed` by default — for waving an agent on without typing the same reply again.
+- 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.5.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 +44,98 @@ 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.
+
+## Resizing panes and the sidebar
+
+Drag the line between two panes, or the sidebar's right edge, to change how the
+space is shared. Sizes are remembered between launches and clamped so that no
+pane can be dragged down to nothing.
+
+The dividers take keyboard focus as well: the arrow keys nudge one two percent at
+a time, and Enter or a double-click puts it back in the middle. One divider
+position is shared by every layout, so a split you set up in the vertical split
+is the same split you get in the four-pane grid.
+
+## 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. Also the phrase the pane's
+  proceed button sends, described below.
+- **Speech recognition** — engine, model and tuning, described below.
+
+### Proceed button
+
+Each pane's title bar carries a tick beside the microphone. Clicking it sends
+`OK, proceed` and presses Enter — for the common case of an AI coding agent
+pausing to ask whether it should carry on. The phrase is editable under
+**Settings ▸ AI & voice**, so an agent that responds better to different wording
+can have it.
+
+This is the one control that presses Enter for you; voice transcripts and AI
+suggestions deliberately do not. It sends to the pane it belongs to, so a pane
+sitting at a shell prompt rather than in an agent will simply try to run the
+phrase as a command.
+
+### 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 +146,43 @@ npm run build
 npm start
 ```
 
-After installing the published package, launch ZeroG Terminal with:
+Node.js is the only prerequisite every host needs. The scripts above run on Linux
+and Windows; npm runs them through `cmd.exe` on Windows, so no POSIX shell is
+required whichever shell you start them from.
 
-```bash
-npx zerogterm
-```
+`node-pty` provides terminal I/O on every platform. It ships prebuilt binaries
+for Windows and macOS, so a C/C++ toolchain is a Linux requirement rather than a
+general one — there, `npm install` compiles it.
 
-Runtime prerequisites on the host:
+### Linux
 
 ```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:
+`make`, `gcc-c++` and `python3` build `node-pty`. `screen` is optional but worth
+having: with it, local sessions are persistent and rediscovered after relaunch.
+Without it, ZeroG falls back to a direct PTY on the chosen shell and labels the
+session process-only; that shell is lost when the application exits.
 
-```bash
-sudo dnf install screen
-```
+### Windows
 
-## Current verification
+No tooling beyond Node.js. The new-terminal dialog offers the shells it finds on
+PATH — Windows PowerShell, PowerShell 7, Command Prompt, WSL (with a distribution
+picker), and Git Bash where Git for Windows is installed.
+
+`screen` does not exist on Windows, so local sessions are always process-only and
+do not survive app exit. Remote SSH sessions are unaffected by the local shell
+backend, and a remote host with `screen` still gives persistent sessions there.
+
+## 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 (167 tests covering session service behaviour and PTY sizing, shell discovery, SSH inventory and argument validation, remote-screen parsing and prompt readiness, session history, the session dialog, settings, terminal clipboard and OSC 52 handling, dialog dismissal, and the speech and voice helpers; one further test needs a real `screen` and is opt-in through `ZEROG_LIVE_SCREEN=1`).
 - `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,13 +1,24 @@
 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));
 const history = new SessionHistoryStore({ filePath: defaultHistoryPath(app.getPath('userData')) });
 const service = new ScreenService({ onEvent: (event, session, available) => { void history.record(event, session, available); } });
 let win;
+/** A pane's measured size, as it arrives from the renderer. */
+function parsePtySize(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const { cols, rows } = value;
+    if (!Number.isInteger(cols) || !Number.isInteger(rows))
+        return undefined;
+    return { cols: cols, rows: rows };
+}
 // GPU is unstable under Toolbox/Wayland on this host; allow override.
 if (process.env.ZEROG_ENABLE_GPU !== '1') {
     app.disableHardwareAcceleration();
@@ -106,10 +117,10 @@ ipcMain.handle('screens:attachRemote', (_event, input, screenName) => {
         throw new Error('screenName is required');
     return buildRemoteScreenAttachArgs(connection, screenName);
 });
-ipcMain.handle('sessions:attach', (_event, id) => {
+ipcMain.handle('sessions:attach', (_event, id, size) => {
     if (typeof id !== 'string' || !id)
         throw new Error('attachSession requires a session id');
-    return service.attach(id, (data) => win?.webContents.send('terminal:data', id, data), (message) => win?.webContents.send('terminal:status', id, message));
+    return service.attach(id, (data) => win?.webContents.send('terminal:data', id, data), (message) => win?.webContents.send('terminal:status', id, message), parsePtySize(size));
 });
 ipcMain.handle('sessions:close', (_event, id) => {
     if (typeof id !== 'string' || !id)
@@ -128,7 +139,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/preload.cjs

@@ -11,7 +11,7 @@ const api = {
   listKnownConnections: () => ipcRenderer.invoke('connections:listKnown'),
   discoverRemoteScreens: (connection) => ipcRenderer.invoke('screens:discoverRemote', connection),
   buildRemoteScreenAttach: (connection, screenName) => ipcRenderer.invoke('screens:attachRemote', connection, screenName),
-  attachSession: (id) => ipcRenderer.invoke('sessions:attach', id),
+  attachSession: (id, size) => ipcRenderer.invoke('sessions:attach', id, size),
   closeSession: (id) => ipcRenderer.invoke('sessions:close', id),
   write: (sessionId, data) => ipcRenderer.send('terminal:write', sessionId, data),
   resize: (sessionId, cols, rows) => ipcRenderer.send('terminal:resize', sessionId, cols, rows),

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

@@ -3,6 +3,7 @@ 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}$/;
@@ -13,6 +14,26 @@ const NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,48}$/;
  * -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}))?$/;
+/**
+ * Size a pty starts at when the pane could not be measured — a placeholder,
+ * not a preference. Panes pass their real size through attach().
+ */
+const FALLBACK_SIZE = { cols: 120, rows: 32 };
+/**
+ * A size a pty can actually be given. Sizes cross the IPC boundary from the
+ * renderer, and a zero or fractional one is rejected by ConPTY (and makes
+ * every full-screen program wrap in the wrong place on Unix).
+ */
+function usableSize(size) {
+    if (!size)
+        return undefined;
+    const { cols, rows } = size;
+    if (!Number.isInteger(cols) || !Number.isInteger(rows))
+        return undefined;
+    if (cols < 2 || rows < 2 || cols > 2000 || rows > 2000)
+        return undefined;
+    return { cols, rows };
+}
 export function validateSessionName(name) {
     const value = name.trim();
     if (!NAME.test(value)) {
@@ -45,30 +66,6 @@ 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')
@@ -110,7 +107,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']);
@@ -154,11 +156,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);
@@ -190,24 +196,39 @@ export class ScreenService {
         this.onEvent?.('created', session, true);
         return session;
     }
-    attach(id, onData, onExit) {
+    /**
+     * Attach a pane to a session, starting its pty if it does not have one.
+     *
+     * `size` is the pane's own measurement. A pty spawned at some stock size and
+     * resized a moment later shows its first frame at the wrong width, and a
+     * full-screen program redrawing over that frame leaves pieces of it behind —
+     * so the shell is started at the size it will actually be displayed at.
+     */
+    attach(id, onData, onExit, size) {
         const existing = this.getSession(id);
-        if (this.ptys.has(id))
+        if (this.ptys.has(id)) {
+            // Re-attaching pane may be a different size than the one that started it.
+            const measured = usableSize(size);
+            if (measured)
+                this.resize(id, measured.cols, measured.rows);
             return { ...existing, status: 'connected' };
+        }
         if (id.startsWith('local:')) {
             const fallback = this.fallbackLocalSessions.get(id);
             if (fallback) {
                 fallback.status = 'connected';
                 fallback.lastSeen = new Date().toISOString();
-                const shell = shellBackendArgs(fallback.backend ?? 'bash', fallback.wslDistribution);
-                this.spawnCommand(id, shell.executable, shell.args, onData, onExit, fallback.cwd);
+                const shell = isLocalShellBackend(fallback.backend)
+                    ? resolveShellBackend(fallback.backend, fallback.wslDistribution)
+                    : defaultShellBackend();
+                this.spawnCommand(id, shell.executable, shell.args, onData, onExit, fallback.cwd, size);
                 this.onEvent?.('attached', fallback, true);
                 return { ...fallback };
             }
             // 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.spawnCommand(id, 'screen', ['-x', name], onData, onExit, homedir(), size);
             this.onEvent?.('attached', existing, true);
             return { ...existing, status: 'connected', persistence: 'screen' };
         }
@@ -219,7 +240,7 @@ export class ScreenService {
         session.status = 'connected';
         session.lastSeen = new Date().toISOString();
         try {
-            this.spawnCommand(id, 'ssh', args, onData, onExit);
+            this.spawnCommand(id, 'ssh', args, onData, onExit, homedir(), size);
         }
         catch (error) {
             session.status = 'error';
@@ -251,12 +272,12 @@ export class ScreenService {
             throw new Error(`Unknown session: ${id}`);
         return session;
     }
-    spawnCommand(sessionId, file, args, onData, onExit, cwd = homedir()) {
-        const pty = loadPty();
-        const proc = pty.spawn(file, args, {
+    spawnCommand(sessionId, file, args, onData, onExit, cwd = homedir(), size) {
+        const { cols, rows } = usableSize(size) ?? FALLBACK_SIZE;
+        const proc = this.spawnPty(file, args, {
             name: 'xterm-256color',
-            cols: 120,
-            rows: 32,
+            cols,
+            rows,
             cwd,
             env: process.env
         });
@@ -272,7 +293,7 @@ export class ScreenService {
                 }
             }
         };
-        this.ptys.set(sessionId, { handle, kind: sessionId.startsWith('ssh:') ? 'ssh' : 'local' });
+        this.ptys.set(sessionId, { handle, kind: sessionId.startsWith('ssh:') ? 'ssh' : 'local', cols, rows });
         proc.onData(onData);
         proc.onExit(() => {
             this.ptys.delete(sessionId);
@@ -294,8 +315,25 @@ export class ScreenService {
     write(sessionId, data) {
         this.ptys.get(sessionId)?.handle.write(data);
     }
+    /**
+     * Tell a session's pty how big its pane is now.
+     *
+     * A resize is not free and not invisible: it makes ConPTY reflow and re-emit
+     * its screen, and every full-screen program redraw on SIGWINCH. Panes refit
+     * on layout, font and status changes, which mostly produce the size the pty
+     * already has, so a repeat of the current size is dropped rather than paid
+     * for in a torn redraw.
+     */
     resize(sessionId, cols, rows) {
-        this.ptys.get(sessionId)?.handle.resize(cols, rows);
+        const pty = this.ptys.get(sessionId);
+        if (!pty)
+            return;
+        const size = usableSize({ cols, rows });
+        if (!size || (size.cols === pty.cols && size.rows === pty.rows))
+            return;
+        pty.cols = size.cols;
+        pty.rows = size.rows;
+        pty.handle.resize(size.cols, size.rows);
     }
     detach(sessionId) {
         this.ptys.get(sessionId)?.handle.kill();
@@ -318,10 +356,3 @@ export class ScreenService {
         this.onEvent?.('closed', session, false);
     }
 }
-async function executableAvailable(executable) { try {
-    await execFileAsync(executable, ['--version']);
-    return true;
-}
-catch {
-    return false;
-} }