zerogterm 0.6.0-alpha.1 → 0.7.0-alpha2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Stephen Phillips
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Stephen Phillips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,13 +7,16 @@ ZeroG Terminal is an alpha project, but it is already useful as a multi-session
 ## 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.
+- Draggable dividers between panes and beside the sidebar, so a split does not have to be an even one. Sizes are remembered between launches.
+- A compact navigation rail for sessions, overview, settings, SSH connections, and opening a new local terminal, while keeping the sessions sidebar collapsible.
+- Layout controls that restore a split, even up its pane sizes, and maximize or restore a pane in a predictable sequence.
 - 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.
+- 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.
 - 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.
@@ -31,7 +34,7 @@ See the project walkthrough on [YouTube](https://youtu.be/4aJZCxLHD14).
 
 ## Release status
 
-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).
+ZeroG Terminal is currently a public alpha. The current release is `0.7.0-alpha2`; 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.
 
@@ -47,6 +50,13 @@ The npm package contains the built Electron application and project documentatio
 - `Ctrl+Shift+,` — settings
 - `Esc` — close overview / dialogs, cancel voice recording
 
+Clicking a link in a pane opens it in your own browser rather than in a window
+of ZeroG. Hovering one first shows where it actually goes in the status bar,
+which matters because a terminal hyperlink can be labelled with anything. Only
+web links and `mailto:` addresses are opened; anything else says so in the
+status bar instead, since a link in terminal output can name a scheme that would
+start local software.
+
 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
@@ -64,6 +74,37 @@ 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.
 
+## Transferring files over SFTP
+
+The ⇅ button above the panes opens a two-pane transfer panel: this computer on
+the left, the active SSH session's host on the right. It is only available while
+an SSH session is selected, and the button says why when it is not.
+
+The connection is made with the system `sftp` client, so it uses the same
+`~/.ssh/config`, agent, keys, and `known_hosts` as the terminal beside it. A
+password, a key passphrase, or an unknown host key is asked for inside the
+panel — ZeroG never answers a host-key question on your behalf, and the
+fingerprint is shown with the question. Nothing typed there is stored.
+
+The remote side opens at the directory the terminal's shell is currently in,
+where that can be known without disturbing the session. ZeroG reads it from
+OSC 7 — the sequence a shell emits to report its directory — and otherwise from
+the path in the prompt; it never types `pwd` into your session to find out. When
+neither is available the panel opens at the login directory.
+
+Select files with a click, or several with Ctrl-click or Shift-click, then Upload or Download.
+Double-click a folder to open it, or type a path into the folder box. New folder,
+rename, and delete act on one selected item; deleting asks first, and a folder
+must be empty, so a single click can never remove a tree. Remote folders can be
+downloaded recursively with the system `sftp` client; uploads remain file-only,
+so a local folder is never copied accidentally as a different job.
+
+Filenames containing quotes, backslashes, or the wildcard characters `* ? [ ]`
+are refused with a message rather than acted on. The `sftp` client re-reads its
+own arguments through a glob pass, and there is no encoding of those characters
+that is provably correct for every command — being approximately right about
+which file to delete is not good enough.
+
 ## Settings
 
 Settings open from the gear at the bottom of the left rail, the avatar in the
@@ -180,7 +221,7 @@ backend, and a remote host with `screen` still gives persistent sessions there.
 The current main branch has the following local verification coverage:
 
 - `npm run typecheck`: passes.
-- `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 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 run build`: passes and writes `dist/main` plus `dist/renderer`.
 - `npm audit --omit=dev`: production dependency auditing is part of the project quality checks.
 

package/bin/zerogterm.cjs

@@ -1,23 +1,23 @@
-#!/usr/bin/env node
-
-const { spawn } = require('node:child_process');
-const path = require('node:path');
-const electron = require('electron');
-
-const packageRoot = path.resolve(__dirname, '..');
-const child = spawn(electron, [packageRoot, ...process.argv.slice(2)], {
-  stdio: 'inherit'
-});
-
-child.on('error', (error) => {
-  console.error(`Failed to start ZeroG Terminal: ${error.message}`);
-  process.exitCode = 1;
-});
-
-child.on('close', (code, signal) => {
-  if (signal) {
-    process.kill(process.pid, signal);
-    return;
-  }
-  process.exitCode = code ?? 1;
-});
+#!/usr/bin/env node
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const electron = require('electron');
+
+const packageRoot = path.resolve(__dirname, '..');
+const child = spawn(electron, [packageRoot, ...process.argv.slice(2)], {
+  stdio: 'inherit'
+});
+
+child.on('error', (error) => {
+  console.error(`Failed to start ZeroG Terminal: ${error.message}`);
+  process.exitCode = 1;
+});
+
+child.on('close', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});

package/dist/main/main/external-links.js

@@ -0,0 +1,79 @@
+// Deciding which links may leave the application, and by which door.
+//
+// A link in a pane is not something the user wrote: it arrives in terminal
+// output, which SECURITY.md is explicit about treating as untrusted. Worse, OSC 8
+// lets a remote host display one thing and link to another, so the URL handed
+// over here has no relationship to the text the user clicked on.
+//
+// The operating system will do a great deal with a URL. `file:` reaches the local
+// disk; on Windows `smb:` reaches a network share and leaks credentials to it;
+// and installed applications register their own schemes, some of which take a
+// path or a command. Handing any of those to the shell on a single click would
+// make a remote host's output into a way of starting local software. So this is
+// an allowlist, not a blocklist: the schemes a person means when they click a
+// link in a terminal, and nothing else.
+//
+// Kept pure and free of Electron so the rule can be tested directly.
+/** Schemes worth opening: the web, and an address to write to. */
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'mailto:']);
+/**
+ * A URL is only long enough to be suspicious once it is absurd. The limit is
+ * here because the string is passed to the operating system, not because a real
+ * link is ever near it.
+ */
+const MAX_URL = 2048;
+/** Written as escapes: a literal control character in source is invisible. */
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
+/**
+ * Should this link be handed to the system browser?
+ *
+ * The URL is re-parsed rather than pattern-matched: a scheme is only what the
+ * parser says it is, and `java\tscript:` or a leading space are not the checks a
+ * regex tends to get right. The parsed form is what gets returned, so the value
+ * that reaches the shell is the one that was inspected.
+ */
+export function decideExternalLink(value) {
+    if (typeof value !== 'string' || !value.trim()) {
+        return { open: false, reason: 'That link is empty.' };
+    }
+    if (value.length > MAX_URL) {
+        return { open: false, reason: 'That link is too long to open.' };
+    }
+    // A control character cannot appear in a URL, and its presence means the value
+    // was assembled to be read one way and used another.
+    if (CONTROL_CHARACTER.test(value)) {
+        return { open: false, reason: 'That link contains control characters.' };
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return { open: false, reason: 'That is not a link this can open.' };
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        // Name the scheme: the user clicked something that looked like a link, and
+        // "refused" without saying why is not enough to judge what just happened.
+        return { open: false, reason: `ZeroG only opens web links; this one is ${parsed.protocol.replace(':', '')}.` };
+    }
+    return { open: true, url: parsed.href };
+}
+/**
+ * Is this URL the application's own window content?
+ *
+ * Used to tell a genuine outward link from the app navigating itself — the dev
+ * server and the packaged `file:` index are the only two things the window is
+ * ever meant to be showing.
+ */
+export function isApplicationUrl(value, current) {
+    if (value === current)
+        return true;
+    try {
+        const target = new URL(value);
+        const app = new URL(current);
+        return target.origin === app.origin && target.pathname === app.pathname;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/main/main/local-fs.js

@@ -0,0 +1,115 @@
+// The local half of the transfer panel: directory listings and the three edits
+// the panel can make locally.
+//
+// Nothing here reads file *contents*. The renderer is sandboxed and has no
+// filesystem access of its own, and this module is deliberately the narrowest
+// widening of that boundary that a file browser needs: names, sizes, kinds, and
+// explicit create/rename/delete on a path the user pointed at.
+import { constants } from 'node:fs';
+import { access, lstat, mkdir, readdir, rename, rm, rmdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
+import { sortEntries } from '../shared/files.js';
+/**
+ * A path this process will act on.
+ *
+ * Paths arrive from the renderer, so they are re-derived here rather than
+ * trusted: NUL terminates the path for the C library underneath and can make a
+ * check and the later operation disagree about which file is meant, and a
+ * relative path would resolve against whatever directory the app happens to
+ * have — never something the user chose.
+ */
+export function resolveLocalPath(input) {
+    if (typeof input !== 'string' || !input)
+        throw new Error('A filesystem path is required.');
+    if (input.includes('\0'))
+        throw new Error('That path is not valid.');
+    if (input.length > 4096)
+        throw new Error('That path is too long.');
+    const expanded = input === '~' || input.startsWith('~/') || input.startsWith('~\\')
+        ? join(homedir(), input.slice(1))
+        : input;
+    if (!isAbsolute(expanded))
+        throw new Error('Only absolute paths can be browsed.');
+    return resolve(normalize(expanded));
+}
+export function localHome() {
+    return homedir();
+}
+/**
+ * List a directory.
+ *
+ * A stat per entry is what makes kind and size real, and it is allowed to fail:
+ * a broken symlink or a file that has just been deleted should leave a row in
+ * the listing rather than emptying the pane.
+ *
+ * Entries are stat'd with lstat, so a symlink is reported as a symlink whatever
+ * it points at. Reporting a link to a directory as a directory instead would be
+ * a lie with consequences: deleting it would use `rmdir`, which refuses a
+ * symlink, so the row could not be removed at all. It also matches what the
+ * remote side shows, since `ls -l` describes the link rather than its target.
+ * Entering one still works — see isNavigable — because opening it simply reads
+ * through, and a link to a file reports that it is not a directory.
+ */
+export async function listLocalDirectory(path) {
+    const target = path ? resolveLocalPath(path) : homedir();
+    await access(target, constants.R_OK);
+    const dirents = await readdir(target, { withFileTypes: true });
+    const entries = await Promise.all(dirents.map(async (dirent) => {
+        const full = join(target, dirent.name);
+        try {
+            const info = await lstat(full);
+            return {
+                name: dirent.name,
+                kind: info.isSymbolicLink() ? 'symlink' : info.isDirectory() ? 'directory' : 'file',
+                size: info.size,
+                modified: info.mtime.toISOString()
+            };
+        }
+        catch {
+            return { name: dirent.name, kind: dirent.isSymbolicLink() ? 'symlink' : dirent.isDirectory() ? 'directory' : 'file', size: 0 };
+        }
+    }));
+    return { path: target, entries: sortEntries(entries) };
+}
+export async function createLocalDirectory(path) {
+    // No recursive create: the panel creates one folder in the directory on
+    // screen, and a mistyped path should fail rather than build a tree.
+    await mkdir(resolveLocalPath(path));
+}
+/**
+ * Rename an entry, refusing to land on a name that is already taken.
+ *
+ * rename() would silently replace an existing file, and the panel's rename is a
+ * relabel rather than an overwrite. The check is not atomic: nothing in Node's
+ * API offers a no-clobber rename on both platforms, so a different process that
+ * creates that name in the moment between the check and the rename would still
+ * be overwritten. That is a guard against the user's own mistake — the name is
+ * already in the folder they are looking at — not a guarantee against another
+ * writer, and anything able to win that race could equally overwrite the file
+ * directly.
+ */
+export async function renameLocalEntry(from, to) {
+    const source = resolveLocalPath(from);
+    const destination = resolveLocalPath(to);
+    const clash = await lstat(destination).then(() => true, () => false);
+    if (clash)
+        throw new Error('Something with that name already exists here.');
+    await rename(source, destination);
+}
+/**
+ * Delete one entry.
+ *
+ * Directories use rmdir, so a non-empty one fails: this panel deletes what the
+ * user pointed at, and a recursive local delete triggered by a single click is
+ * not a mistake worth making possible.
+ */
+export async function removeLocalEntry(path, kind) {
+    const target = resolveLocalPath(path);
+    if (target === resolve(homedir()))
+        throw new Error('Refusing to delete the home directory.');
+    if (kind === 'directory')
+        await rmdir(target);
+    else
+        await rm(target, { force: false });
+}

package/dist/main/main/main.js

@@ -1,4 +1,4 @@
-import { app, BrowserWindow, clipboard, ipcMain, Menu, session } from 'electron';
+import { app, BrowserWindow, clipboard, ipcMain, Menu, session, shell } from 'electron';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writeClipboardText } from './clipboard.js';
@@ -6,10 +6,16 @@ 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';
+import { createLocalDirectory, listLocalDirectory, localHome, removeLocalEntry, renameLocalEntry } from './local-fs.js';
+import { decideExternalLink, isApplicationUrl } from './external-links.js';
+import { SftpService } from './sftp-service.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;
+// Transfer connections outlive any single panel opening, so the panel can be
+// closed and reopened without re-authenticating to the host.
+const sftp = new SftpService({ onEvent: (event) => win?.webContents.send('sftp:event', event) });
 /** A pane's measured size, as it arrives from the renderer. */
 function parsePtySize(value) {
     if (!value || typeof value !== 'object')
@@ -41,6 +47,29 @@ function createWindow() {
             sandbox: true
         }
     });
+    // A link in a pane belongs in the user's browser, not in a window of this app.
+    //
+    // Electron's default answer to window.open is a new BrowserWindow, and xterm
+    // activates an OSC 8 hyperlink by calling exactly that — so clicking a link in
+    // a terminal opened a bare Electron window with no address bar, no profile and
+    // no extensions, which is nobody's browser. Both handlers below refuse to
+    // navigate and hand the URL to the desktop instead.
+    //
+    // They are also the backstop for the renderer's own link handling: whatever
+    // asks for a window here, from any code path now or later, cannot get one.
+    win.webContents.setWindowOpenHandler(({ url }) => {
+        openExternalLink(url);
+        return { action: 'deny' };
+    });
+    // The same for a link that would replace the workspace with a web page, which
+    // would take every pane down with it.
+    const contents = win.webContents;
+    contents.on('will-navigate', (event, url) => {
+        if (isApplicationUrl(url, contents.getURL()))
+            return;
+        event.preventDefault();
+        openExternalLink(url);
+    });
     win.webContents.on('did-fail-load', (_event, code, desc, url) => {
         console.error('[zerog] did-fail-load', { code, desc, url });
     });
@@ -61,11 +90,41 @@ function createWindow() {
     win.on('closed', () => {
         win = undefined;
         service.detachAll();
+        sftp.closeAll();
     });
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
+/**
+ * Hand a link to the desktop, if it is one this should open.
+ *
+ * The decision is in external-links.ts and is an allowlist of schemes: the URL
+ * comes from terminal output, and the operating system will do a great deal more
+ * with `file:` or an application's own scheme than open a web page. A refusal is
+ * reported in the status bar rather than silently dropped, so a click that does
+ * nothing still says why.
+ */
+function openExternalLink(url) {
+    const decision = decideExternalLink(url);
+    if (!decision.open) {
+        win?.webContents.send('links:refused', decision.reason);
+        console.warn('[zerog] refused to open link', { url, reason: decision.reason });
+        return;
+    }
+    void shell.openExternal(decision.url).catch((error) => {
+        win?.webContents.send('links:refused', 'That link could not be opened.');
+        console.error('[zerog] openExternal failed', error);
+    });
+}
+ipcMain.handle('links:openExternal', (_event, url) => {
+    const decision = decideExternalLink(url);
+    // Rejecting rather than resolving quietly: the renderer puts the reason in the
+    // status bar, so the user is never told nothing at all.
+    if (!decision.open)
+        throw new Error(decision.reason);
+    return shell.openExternal(decision.url);
+});
 ipcMain.handle('sessions:list', () => service.list());
 ipcMain.handle('sessions:history', () => history.list());
 ipcMain.handle('sessions:historyRemove', (_event, entryId) => history.remove(entryId));
@@ -146,6 +205,37 @@ ipcMain.handle('clipboard:writeText', (_event, text) => {
     }
 });
 ipcMain.handle('clipboard:readText', () => clipboard.readText());
+/** A string that crossed the IPC boundary and is about to be used as one. */
+function requireString(value, field) {
+    if (typeof value !== 'string' || !value)
+        throw new Error(`${field} is required.`);
+    return value;
+}
+function requireEntryKind(value) {
+    if (value === 'file' || value === 'directory' || value === 'symlink')
+        return value;
+    throw new Error('An entry kind of file, directory, or symlink is required.');
+}
+ipcMain.handle('fs:localHome', () => localHome());
+ipcMain.handle('fs:listLocal', (_event, path) => listLocalDirectory(typeof path === 'string' && path ? path : undefined));
+ipcMain.handle('fs:mkdirLocal', (_event, path) => createLocalDirectory(requireString(path, 'A folder path')));
+ipcMain.handle('fs:renameLocal', (_event, from, to) => renameLocalEntry(requireString(from, 'The current path'), requireString(to, 'The new path')));
+ipcMain.handle('fs:removeLocal', (_event, path, kind) => removeLocalEntry(requireString(path, 'A path'), requireEntryKind(kind)));
+ipcMain.handle('sftp:open', (_event, target, cwd) => sftp.open(requireString(target, 'An SSH target'), typeof cwd === 'string' && cwd ? cwd : undefined));
+ipcMain.handle('sftp:list', (_event, id, path) => sftp.list(requireString(id, 'A transfer connection'), typeof path === 'string' && path ? path : undefined));
+ipcMain.handle('sftp:mkdir', (_event, id, path) => sftp.mkdir(requireString(id, 'A transfer connection'), requireString(path, 'A folder path')));
+ipcMain.handle('sftp:rename', (_event, id, from, to) => sftp.rename(requireString(id, 'A transfer connection'), requireString(from, 'The current path'), requireString(to, 'The new path')));
+ipcMain.handle('sftp:remove', (_event, id, path, kind) => sftp.remove(requireString(id, 'A transfer connection'), requireString(path, 'A path'), requireEntryKind(kind)));
+ipcMain.handle('sftp:upload', (_event, id, localPath, remoteDir) => sftp.upload(requireString(id, 'A transfer connection'), requireString(localPath, 'A local file'), requireString(remoteDir, 'A remote folder')));
+ipcMain.handle('sftp:download', (_event, id, remotePath, localDir, kind) => sftp.download(requireString(id, 'A transfer connection'), requireString(remotePath, 'A remote path'), requireString(localDir, 'A local folder'), requireEntryKind(kind)));
+// The answer is a secret in two of the three cases, so it is passed straight
+// through and never returned, logged, or kept.
+ipcMain.handle('sftp:answerPrompt', (_event, id, answer) => {
+    if (typeof answer !== 'string')
+        throw new Error('An answer is required.');
+    sftp.answerPrompt(requireString(id, 'A transfer connection'), answer);
+});
+ipcMain.handle('sftp:close', (_event, id) => sftp.close(requireString(id, 'A transfer connection')));
 ipcMain.handle('ai:suggest', () => ({
     command: 'git status --short',
     explanation: 'Read-only preview of changed files in the active workspace.'

package/dist/main/main/preload.cjs

@@ -27,7 +27,32 @@ const api = {
     ipcRenderer.on('terminal:status', listener);
     return () => ipcRenderer.removeListener('terminal:status', listener);
   },
-  requestAiCommand: () => ipcRenderer.invoke('ai:suggest')
+  requestAiCommand: () => ipcRenderer.invoke('ai:suggest'),
+  listLocalDirectory: (path) => ipcRenderer.invoke('fs:listLocal', path),
+  localHome: () => ipcRenderer.invoke('fs:localHome'),
+  createLocalDirectory: (path) => ipcRenderer.invoke('fs:mkdirLocal', path),
+  renameLocalEntry: (from, to) => ipcRenderer.invoke('fs:renameLocal', from, to),
+  removeLocalEntry: (path, kind) => ipcRenderer.invoke('fs:removeLocal', path, kind),
+  sftpOpen: (target, cwd) => ipcRenderer.invoke('sftp:open', target, cwd),
+  sftpList: (sessionId, path) => ipcRenderer.invoke('sftp:list', sessionId, path),
+  sftpMkdir: (sessionId, path) => ipcRenderer.invoke('sftp:mkdir', sessionId, path),
+  sftpRename: (sessionId, from, to) => ipcRenderer.invoke('sftp:rename', sessionId, from, to),
+  sftpRemove: (sessionId, path, kind) => ipcRenderer.invoke('sftp:remove', sessionId, path, kind),
+  sftpUpload: (sessionId, localPath, remoteDir) => ipcRenderer.invoke('sftp:upload', sessionId, localPath, remoteDir),
+  sftpDownload: (sessionId, remotePath, localDir, kind) => ipcRenderer.invoke('sftp:download', sessionId, remotePath, localDir, kind),
+  sftpAnswerPrompt: (sessionId, answer) => ipcRenderer.invoke('sftp:answerPrompt', sessionId, answer),
+  sftpClose: (sessionId) => ipcRenderer.invoke('sftp:close', sessionId),
+  onSftpEvent: (callback) => {
+    const listener = (_event, payload) => callback(payload);
+    ipcRenderer.on('sftp:event', listener);
+    return () => ipcRenderer.removeListener('sftp:event', listener);
+  },
+  openExternal: (url) => ipcRenderer.invoke('links:openExternal', url),
+  onLinkRefused: (callback) => {
+    const listener = (_event, reason) => callback(reason);
+    ipcRenderer.on('links:refused', listener);
+    return () => ipcRenderer.removeListener('links:refused', listener);
+  }
 };
 
 contextBridge.exposeInMainWorld('zerog', api);

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

@@ -1,11 +1,9 @@
 import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { promisify } from 'node:util';
-import { defaultShellBackend, isLocalShellBackend, resolveShellBackend } from './shell-catalog.js';
+import { defaultShellBackend, findOpenSshTool, 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}$/;
@@ -16,17 +14,6 @@ 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}))?$/;
-function resolveSshExecutable() {
-    if (process.platform !== 'win32')
-        return 'ssh';
-    const windowsRoot = process.env.SystemRoot ?? 'C:\\Windows';
-    const candidates = [
-        join(windowsRoot, 'System32', 'OpenSSH', 'ssh.exe'),
-        join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Git', 'usr', 'bin', 'ssh.exe'),
-        join(process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)', 'Git', 'usr', 'bin', 'ssh.exe')
-    ];
-    return candidates.find((candidate) => existsSync(candidate)) ?? 'ssh.exe';
-}
 /**
  * Size a pty starts at when the pane could not be measured — a placeholder,
  * not a preference. Panes pass their real size through attach().
@@ -54,7 +41,13 @@ export function validateSessionName(name) {
     }
     return value;
 }
-export function validateSshTarget(input) {
+/**
+ * Split an SSH target into the pieces a client needs, rejecting anything that
+ * is not one. Shared with the SFTP side (see sftp-protocol.ts) so that both
+ * clients are handed destinations vetted by the same rule — a target ssh would
+ * read as an option must not become an sftp option either.
+ */
+export function parseSshTarget(input) {
     const value = input.trim();
     const match = value.match(SSH_TARGET);
     if (!match) {
@@ -67,13 +60,38 @@ export function validateSshTarget(input) {
             throw new Error('SSH port must be between 1 and 65535.');
         }
     }
-    const destination = user ? `${user}@${host}` : host;
+    return {
+        target: value,
+        destination: user ? `${user}@${host}` : host,
+        ...(user ? { user } : {}),
+        host,
+        ...(portText ? { port: portText } : {})
+    };
+}
+export function validateSshTarget(input) {
+    const { target, destination, port } = parseSshTarget(input);
     const args = ['-tt'];
-    if (portText)
-        args.push('-p', portText);
+    if (port)
+        args.push('-p', port);
     // '--' ends option parsing, so the destination can never be read as a flag.
     args.push('--', destination);
-    return { target: value, args };
+    return { target, args };
+}
+/**
+ * The ssh client, as a path a pty can actually start.
+ *
+ * node-pty passes the file straight to CreateProcess on Windows, which does not
+ * append `.exe` — so a pty asked for `ssh` fails with "File not found" on a
+ * machine that has it. Resolving it here also turns a missing client into a
+ * sentence rather than that message. Where OpenSSH is looked for lives in
+ * findOpenSshTool, shared with the transfer side's sftpExecutable.
+ */
+export function sshExecutable(options = {}) {
+    const file = findOpenSshTool('ssh', options);
+    if (!file) {
+        throw new Error('The OpenSSH client was not found. Install the OpenSSH client tools to connect over SSH.');
+    }
+    return file;
 }
 export function parseWslDistributions(output) {
     return output.split(/\r?\n/).slice(1).map((line) => line.replace(/^\*?\s*/, '').trim())
@@ -253,7 +271,7 @@ export class ScreenService {
         session.status = 'connected';
         session.lastSeen = new Date().toISOString();
         try {
-            this.spawnCommand(id, resolveSshExecutable(), args, onData, onExit, homedir(), size);
+            this.spawnCommand(id, sshExecutable(), args, onData, onExit, homedir(), size);
         }
         catch (error) {
             session.status = 'error';