zerogterm 0.9.4-alpha.1 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+ZeroG Terminal is 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
 
@@ -15,7 +15,8 @@ ZeroG Terminal is an alpha project, but it is already useful as a multi-session
 - SSH sessions for hosts, `user@host`, and `user@host:port` targets.
 - SSH configuration discovery from known connections, including remote `screen` session discovery. In the sidebar's Connections tab, clicking a saved connection opens the connect dialog with the host filled in, and double-clicking it skips the dialog and opens the host in a new pane.
 - 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.
+- Remote screen discovery for the selected SSH destination, including manually entered hosts, with refresh and visible failure states. Background discovery uses key/agent authentication; password-only hosts cannot be queried through the terminal connection.
+- Remote screen attachment launched directly through SSH, preserving the account, custom port and SSH config alias, with authentication and host-key prompts left to the user.
 - Shared ports over SSH, in a Ports view opened from the rail: forward a port on a remote host so it answers on this machine, or a port here so it answers on the remote. Each tunnel is its own SSH connection, so a host needs no terminal open first. Ports bind to loopback unless you widen them, and are remembered between launches.
 - A directory browser inside a pane, opened from the folder button in its title bar: the pane splits, terminal on one side and the directories on the other, with a draggable divider. Double-click a folder to take the shell there. It works on SSH panes and on local ones, WSL included, follows a `cd` you type by hand, and is remembered per pane when you switch workspaces or relaunch.
 - An SFTP transfer panel, opened from the ⇅ button above the panes: local files on the left, the active SSH session's host on the right, with upload, download, new folder, rename, and delete. It connects to the host that session is already using and opens at the directory its shell is standing in, so a file can go straight to the project being worked on.
@@ -38,9 +39,9 @@ See the project walkthrough on [YouTube](https://youtu.be/4aJZCxLHD14).
 
 ## Release status
 
-ZeroG Terminal is currently a public alpha. The current release is `0.9.4-alpha.1`; the version history is tracked in [versions.txt](versions.txt). The running version is shown beside the wordmark in the title bar, read from the app itself rather than written into the interface, so it is accurate in a packaged build too.
+ZeroG Terminal 1.0.0 is the first stable release. The current release is `1.0.0`; the version history is tracked in [versions.txt](versions.txt). The running version is shown beside the wordmark in the title bar, read from the app itself rather than written into the interface, so it is accurate in a packaged build too.
 
-The GitHub Releases page provides a Windows x64 installer and portable executable plus a Linux x64 AppImage and Debian package for each desktop release. These alpha builds are intended for early adopters and testing rather than production use. The npm package remains available for developers who prefer to launch ZeroG from Node.js.
+The GitHub Releases page provides a Windows x64 installer and portable executable plus a Linux x64 AppImage and Debian package for each desktop release. The npm package remains available for developers who prefer to launch ZeroG from Node.js.
 
 ## Terminal shortcuts
 
@@ -386,13 +387,13 @@ how the threshold gets tuned for a particular microphone.
 The simplest way to try the published package is through `npx`:
 
 ```bash
-npx zerogterm
+npx --package=electron@43 --package=zerogterm zerogterm
 ```
 
-The package downloads the application and launches it. To use the launcher repeatedly without downloading on each invocation, install it globally:
+The npm launcher needs Electron alongside ZeroG Terminal; the command above installs both into the temporary npx environment. To use the launcher repeatedly without downloading on each invocation, install it globally:
 
 ```bash
-npm install --global zerogterm
+npm install --global electron@43 zerogterm
 zerogterm
 ```
 
@@ -405,14 +406,14 @@ project workspaces, open SSH sessions, and request commands for your approval.
 1. Start ZeroG Terminal with MCP enabled:
 
    ```bash
-   ZEROG_MCP_ENABLED=1 npx zerogterm
+   ZEROG_MCP_ENABLED=1 npx --package=electron@43 --package=zerogterm zerogterm
    ```
 
    On Windows PowerShell, use:
 
    ```powershell
    $env:ZEROG_MCP_ENABLED = "1"
-   npx zerogterm
+   npx --package=electron@43 --package=zerogterm zerogterm
    ```
 
 2. Open **Settings → AI & voice → MCP** in ZeroG Terminal. Copy the displayed
@@ -469,7 +470,7 @@ general one — there, `npm install` compiles it.
 
 ### Desktop releases
 
-Download the latest release for your platform from [GitHub Releases](https://github.com/HappyMonkeyAI/ZeroGTerm/releases). These alpha builds are intended for early adopters and testing rather than production use. Review the release notes before installing; SSH, WSL, PowerShell, Git Bash, and any remote `screen` sessions are provided by the host system rather than bundled with the app.
+Download the latest release for your platform from [GitHub Releases](https://github.com/HappyMonkeyAI/ZeroGTerm/releases). Review the release notes before installing; SSH, WSL, PowerShell, Git Bash, and any remote `screen` sessions are provided by the host system rather than bundled with the app.
 
 #### Windows
 
@@ -502,14 +503,37 @@ picker), and Git Bash where Git for Windows is installed.
 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.
 
+The pinned `node-pty` dependency receives a small ConPTY teardown patch during
+install and build (`scripts/patch-node-pty.mjs`). Review that patch before changing
+its version. Run `node scripts/pty-shutdown-smoke.cjs` on Windows to check forced
+and graceful shutdown with a real child process. Release evaluation evidence and
+remaining sign-off items are in [the release check report](docs/release-readiness-screen-check.md).
+
+Windows source packaging rebuilds native dependencies. Install Visual Studio 2022
+Build Tools with the C++ desktop workload by importing [`.vsconfig`](.vsconfig),
+then run `powershell -ExecutionPolicy Bypass -File scripts/ensure-windows-build-tools.ps1`.
+The helper checks the selected MSVC toolset and installs its missing Spectre libraries
+through Visual Studio Installer if needed; Windows may request administrator approval.
+Then run `npm run package:win`. The normal native rebuild and installed application
+have been verified; compiler protections remain enabled.
+
+Linux packaging uses `/opt/ZeroGTerminal` to avoid Electron's sandbox launcher issue
+with spaces in installation paths; the application menu still says **ZeroG Terminal**.
+The Debian package declares its audio and graphics runtime libraries explicitly.
+
+The Electron downloader has a scoped `global-agent` override to remove the vulnerable
+`sprintf-js` dependency chain. `node scripts/check-downloader-proxy.mjs` verifies proxy
+routing and `NO_PROXY` bypass using local fixtures. CI runs this check and the full audit.
+
+
 ## Verification
 
 The current main branch has the following local verification coverage:
 
 - `npm run typecheck`: passes.
-- `npm test`: passes (251 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, the speech and voice helpers, external link handling, and the SFTP transfer path — command quoting, listing and error parsing, authentication prompts, local filesystem operations, and working-directory detection; one further test needs a real `screen` and is opt-in through `ZEROG_LIVE_SCREEN=1`).
+- `npm test`: 64 test files; 1,169 passed and 3 platform skips on Windows, all 1,172 passed on Linux with `ZEROG_LIVE_SCREEN=1`.
 - `npm run build`: passes and writes `dist/main` plus `dist/renderer`.
-- `npm audit --omit=dev`: production dependency auditing is part of the project quality checks.
+- `npm audit --audit-level=moderate`: zero advisories in the verified dependency tree.
 
 ## License
 

package/bin/zerogterm.cjs

@@ -2,7 +2,13 @@
 
 const { spawn } = require('node:child_process');
 const path = require('node:path');
-const electron = require('electron');
+let electron;
+try {
+  electron = require('electron');
+} catch {
+  console.error('Electron runtime was not found. Install both packages: npm install --global electron@43 zerogterm');
+  process.exit(1);
+}
 
 const packageRoot = path.resolve(__dirname, '..');
 const child = spawn(electron, [packageRoot, ...process.argv.slice(2)], {

package/dist/main/main/main.js

@@ -1,9 +1,10 @@
+import { shutdownPtys } from './pty-lifecycle.js';
 import { app, BrowserWindow, clipboard, ipcMain, Menu, safeStorage, session, shell } from 'electron';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { writeClipboardText } from './clipboard.js';
-import { ScreenService, parseWslDistributions } from './session-service.js';
+import { ScreenService, sshExecutable, parseWslDistributions } from './session-service.js';
 import { discoverShellBackends } from './shell-catalog.js';
 import { SessionHistoryStore, defaultHistoryPath } from './session-history.js';
 import { CommandHistoryStore, defaultCommandHistoryPath } from './command-history-store.js';
@@ -517,7 +518,9 @@ ipcMain.handle('sessions:createSsh', async (_event, request) => {
         throw new Error('createSshSession requires { target: string }');
     }
     const name = typeof request.name === 'string' ? request.name : undefined;
-    return service.createSsh(request.target, name);
+    if (request.screenName !== undefined && typeof request.screenName !== 'string')
+        throw new Error('Invalid screen name');
+    return service.createSsh(request.target, name, request.screenName);
 });
 ipcMain.handle('connections:listKnown', () => listKnownConnections());
 ipcMain.handle('screens:discoverRemote', async (_event, input) => {
@@ -526,11 +529,15 @@ ipcMain.handle('screens:discoverRemote', async (_event, input) => {
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
     try {
-        const { stdout } = await promisify(execFile)(command.file, command.args);
+        const { stdout } = await promisify(execFile)(sshExecutable(), command.args, { timeout: 15000, maxBuffer: 256 * 1024 });
         return parseRemoteScreenList(stdout, connection.alias);
     }
     catch (error) {
-        return { status: 'unavailable', host: connection.alias, reason: error?.code === 'ENOENT' ? 'ssh-unavailable' : 'host-unreachable', sessions: [] };
+        // screen exits with 1 when there are no sockets. Other failures must reach
+        // the UI rather than pretending that the host has no running sessions.
+        if (error?.code === 1 && /No Sockets found/i.test(error.stdout ?? ''))
+            return [];
+        throw new Error('Screen discovery failed. Check SSH key/agent access and that screen is installed on the host.');
     }
 });
 ipcMain.handle('screens:attachRemote', (_event, input, screenName) => {
@@ -783,8 +790,27 @@ app.whenReady().then(() => {
             createWindow();
     });
 });
-app.on('before-quit', () => {
-    void agentHooks.stop();
+let shutdownStarted = false;
+let shutdownComplete = false;
+app.on('before-quit', (event) => {
+    if (shutdownComplete)
+        return;
+    event.preventDefault();
+    if (shutdownStarted)
+        return;
+    shutdownStarted = true;
+    service.detachAll();
+    sftp.closeAll();
+    forwards.closeAll();
+    void Promise.allSettled([shutdownPtys(), agentHooks.stop()]).then((results) => {
+        for (const result of results) {
+            if (result.status === 'rejected')
+                console.error('[zerog] shutdown failed', result.reason);
+        }
+    }).finally(() => {
+        shutdownComplete = true;
+        app.quit();
+    });
 });
 app.on('window-all-closed', () => {
     if (process.platform !== 'darwin')

package/dist/main/main/port-forward-service.js

@@ -1,11 +1,8 @@
+import { spawnManagedPty } from './pty-lifecycle.js';
 import { randomUUID } from 'node:crypto';
-import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { FORWARD_SETTLE_MS, buildForwardArgs, describeForward, readForwardOutcome } from './port-forward-protocol.js';
 import { detectPrompt } from './sftp-protocol.js';
-// node-pty is a native addon with no ESM entry point, and this file is compiled
-// as a module. Same shim as session-service.ts and sftp-service.ts.
-const require = createRequire(import.meta.url);
 /** A ceiling on live tunnels, so a stuck panel cannot spawn clients forever. */
 const MAX_FORWARDS = 16;
 /** Nothing at all from the client within this long means the host never answered. */
@@ -33,7 +30,7 @@ export class PortForwardService {
     onEvent;
     settleMs;
     constructor(options = {}) {
-        this.spawnPty = options.spawnPty ?? ((file, args, ptyOptions) => require('node-pty').spawn(file, args, ptyOptions));
+        this.spawnPty = options.spawnPty ?? spawnManagedPty;
         this.onEvent = options.onEvent ?? (() => undefined);
         this.settleMs = options.settleMs ?? FORWARD_SETTLE_MS;
     }

package/dist/main/main/pty-lifecycle.js

@@ -0,0 +1,47 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+/** All three PTY owners must finish native teardown before Electron exits. */
+export class PtyLifecycle {
+    spawn;
+    closing = false;
+    processes = new Map();
+    constructor(spawn) {
+        this.spawn = spawn;
+    }
+    start = (file, args, options) => {
+        if (this.closing)
+            throw new Error('The application is shutting down.');
+        const process = this.spawn(file, args, options);
+        let exited;
+        this.processes.set(process, new Promise((resolve) => { exited = resolve; }));
+        process.onExit(() => { this.processes.delete(process); exited(); });
+        return process;
+    };
+    async shutdown(timeoutMs = 6000) {
+        this.closing = true;
+        const waiting = [...this.processes.values()];
+        for (const process of this.processes.keys()) {
+            try {
+                process.kill();
+            }
+            catch { /* exit callback may already be queued */ }
+        }
+        if (!waiting.length)
+            return;
+        let timer;
+        try {
+            await Promise.race([
+                Promise.all(waiting),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error('PTY shutdown timed out.')), timeoutMs);
+                })
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+const lifecycle = new PtyLifecycle((file, args, options) => require('node-pty').spawn(file, args, options));
+export const spawnManagedPty = lifecycle.start;
+export const shutdownPtys = () => lifecycle.shutdown();

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

@@ -1,11 +1,10 @@
+import { spawnManagedPty } from './pty-lifecycle.js';
 import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
 import { WSL_HOME, defaultShellBackend, findOpenSshTool, isLocalShellBackend, ptyStartDirectory, resolveShellBackend, withWslStartDirectory } 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.
@@ -125,14 +124,6 @@ export function parseScreenList(output) {
         ];
     });
 }
-function loadPty() {
-    try {
-        return require('node-pty');
-    }
-    catch {
-        throw new Error('PTY support is not installed. Run: npm install node-pty (needs make/gcc-c++).');
-    }
-}
 export class ScreenService {
     ptys = new Map();
     sshSessions = new Map();
@@ -150,7 +141,7 @@ export class ScreenService {
     spawnPty;
     constructor(options = {}) {
         this.onEvent = options.onEvent;
-        this.spawnPty = options.spawnPty ?? ((file, args, ptyOptions) => loadPty().spawn(file, args, ptyOptions));
+        this.spawnPty = options.spawnPty ?? spawnManagedPty;
     }
     async available() {
         try {
@@ -221,8 +212,10 @@ export class ScreenService {
         this.onEvent?.('created', session, true);
         return session;
     }
-    async createSsh(targetInput, name) {
+    async createSsh(targetInput, name, screenName) {
         const { target } = validateSshTarget(targetInput);
+        if (screenName !== undefined)
+            validateSessionName(screenName);
         const safeName = validateSessionName(name?.trim() || target.replace(/[^a-zA-Z0-9_.-]+/g, '-').slice(0, 40));
         const session = {
             id: `ssh:${randomUUID()}`,
@@ -233,7 +226,8 @@ export class ScreenService {
             status: 'detached',
             lastSeen: new Date().toISOString(),
             sshTarget: target,
-            backend: 'ssh',
+            backend: screenName ? 'screen' : 'ssh',
+            ...(screenName ? { screenName, persistence: 'screen' } : {}),
             scope: 'remote',
             source: 'active'
         };
@@ -285,6 +279,8 @@ export class ScreenService {
             throw new Error(`Unknown session: ${id}`);
         }
         const { args } = validateSshTarget(session.sshTarget);
+        if (session.screenName)
+            args.push('screen', '-x', validateSessionName(session.screenName));
         session.status = 'connected';
         session.lastSeen = new Date().toISOString();
         try {
@@ -327,7 +323,9 @@ export class ScreenService {
             cols,
             rows,
             cwd,
-            env: process.env
+            // ConPTY does not set TERM from node-pty's name option. OpenSSH needs
+            // it to request a remote terminal that screen can recognise.
+            env: { ...process.env, TERM: 'xterm-256color' }
         });
         const handle = {
             write: (data) => proc.write(data),
@@ -341,9 +339,13 @@ export class ScreenService {
                 }
             }
         };
-        this.ptys.set(sessionId, { handle, kind: sessionId.startsWith('ssh:') ? 'ssh' : 'local', cols, rows });
+        const record = { handle, kind: sessionId.startsWith('ssh:') ? 'ssh' : 'local', cols, rows };
+        this.ptys.set(sessionId, record);
         proc.onData(onData);
         proc.onExit(() => {
+            // A detached PTY can exit after a new attachment already owns this id.
+            if (this.ptys.get(sessionId) !== record)
+                return;
             this.ptys.delete(sessionId);
             const fallback = this.fallbackLocalSessions.get(sessionId);
             if (fallback) {

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

@@ -1,3 +1,4 @@
+import { spawnManagedPty } from './pty-lifecycle.js';
 // The stateful half of SFTP support: one live `sftp` client per remote host,
 // with commands serialised onto it and its answers turned into data by
 // sftp-protocol.ts.
@@ -10,9 +11,7 @@
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { baseName, joinRemote, sortEntries } from '../shared/files.js';
-import { createRequire } from 'node:module';
 import { buildSftpArgs, detectFatal, detectPrompt, endsWithPrompt, findError, isSafeRemotePath, parseListing, parseProgress, lastClientMessage, parsePwd, quoteLocalPath, quoteRemotePath, responseBody } from './sftp-protocol.js';
-const require = createRequire(import.meta.url);
 /**
  * Wide enough that a long `ls -l` record is never wrapped by the pty, which
  * would split one file's row across two lines and lose its name. Rows are
@@ -72,7 +71,7 @@ export class SftpService {
     spawnPty;
     onEvent;
     constructor(options = {}) {
-        this.spawnPty = options.spawnPty ?? ((file, args, ptyOptions) => require('node-pty').spawn(file, args, ptyOptions));
+        this.spawnPty = options.spawnPty ?? spawnManagedPty;
         this.onEvent = options.onEvent ?? (() => undefined);
     }
     /**

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

@@ -102,26 +102,28 @@ export function validateKnownConnection(input) {
 }
 function sshArgs(connection) {
     const c = validateKnownConnection(connection);
-    const destination = c.user ? `${c.user}@${c.hostName ?? c.alias}` : (c.hostName ?? c.alias);
+    // Keep config aliases intact so IdentityFile, ProxyJump and Match still apply.
+    const host = c.source ? c.alias : (c.hostName ?? c.alias);
+    const destination = c.user ? `${c.user}@${host}` : host;
     const args = [];
     if (c.port)
         args.push('-p', String(c.port));
-    args.push(destination, '--');
+    args.push('--', destination);
     return args;
 }
 export function buildRemoteScreenDiscoveryArgs(connection) {
-    return { file: 'ssh', args: [...sshArgs(connection), 'screen', '-ls'] };
+    return { file: 'ssh', args: ['-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', ...sshArgs(connection), 'screen', '-ls'] };
 }
 export function buildRemoteScreenAttachArgs(connection, screenName) {
     if (!SCREEN.test(screenName))
         throw new Error('Invalid screen session name.');
-    return { file: 'ssh', args: [...sshArgs(connection), 'screen', '-x', screenName] };
+    return { file: 'ssh', args: ['-tt', ...sshArgs(connection), 'screen', '-x', screenName] };
 }
 export function parseRemoteScreenList(output, host) {
     if (!TOKEN.test(host))
         throw new Error('Invalid remote host identity.');
     return output.split(/\r?\n/).flatMap((line) => {
-        const match = line.trim().match(/^\d+\.(\S+)\s+\(([^)]+)\)/);
+        const match = line.trim().match(/^\d+\.(\S+)\s+(?:\([^)]*\)\s+)*\((Attached|Detached)\)\s*$/i);
         if (!match || !SCREEN.test(match[1]))
             return [];
         const name = match[1];