zerogterm 0.7.0-alpha2 → 0.7.0-alpha3

package/dist/main/main/secret-store.js

@@ -0,0 +1,156 @@
+// Named secrets, encrypted at rest by the operating system.
+//
+// The renderer keeps its settings in localStorage, which is a plain file on
+// disk: fine for a font choice, wrong for an API key. So keys live here
+// instead, in the main process, encrypted through Electron's safeStorage —
+// DPAPI on Windows, Keychain on macOS, libsecret or kwallet on Linux. The
+// ciphertext file is useless to another user account on the same machine, and
+// nothing readable is written anywhere the renderer can reach.
+//
+// safeStorage can report that encryption is unavailable, which happens on a
+// Linux box with no keyring configured. When it does, storing is refused
+// rather than quietly downgraded to plaintext: a key the user believes is
+// protected must not be written in the clear. The caller is told, and can
+// offer to hold the key in memory for the session instead.
+//
+// The crypto is injected so this module can be tested without Electron.
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const SCHEMA_VERSION = 1;
+/** Thrown when the platform cannot encrypt, so nothing was written. */
+export class EncryptionUnavailableError extends Error {
+    constructor() {
+        super('This system has no secret store available, so the key cannot be saved safely.');
+        this.name = 'EncryptionUnavailableError';
+    }
+}
+export class SecretStore {
+    filePath;
+    crypto;
+    /** Serialised so two saves in flight cannot interleave read-modify-write. */
+    writeQueue = Promise.resolve();
+    constructor(options) {
+        this.filePath = options.filePath;
+        this.crypto = options.crypto;
+    }
+    /** Can this platform encrypt at all? Asked before offering to store a key. */
+    encryptionAvailable() {
+        try {
+            return this.crypto.isEncryptionAvailable();
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Is a secret stored under this name? Does not decrypt it. */
+    async has(name) {
+        const secrets = await this.read();
+        return typeof secrets[name] === 'string';
+    }
+    /**
+     * The stored secret, or null when there is none.
+     *
+     * A value that will not decrypt is treated as absent: that is what a file
+     * copied from another machine or another user account looks like, and there
+     * is nothing to do with it but ask for the key again.
+     */
+    async get(name) {
+        const stored = (await this.read())[name];
+        if (typeof stored !== 'string')
+            return null;
+        try {
+            const value = this.crypto.decryptString(Buffer.from(stored, 'base64'));
+            return value || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Store a secret, replacing any previous one of that name. */
+    async set(name, value) {
+        if (!value) {
+            await this.clear(name);
+            return;
+        }
+        if (!this.encryptionAvailable())
+            throw new EncryptionUnavailableError();
+        const encrypted = this.crypto.encryptString(value).toString('base64');
+        await this.update((secrets) => ({ ...secrets, [name]: encrypted }));
+    }
+    /** Forget a secret. Returns whether there was one. */
+    async clear(name) {
+        let existed = false;
+        await this.update((secrets) => {
+            existed = typeof secrets[name] === 'string';
+            const next = { ...secrets };
+            delete next[name];
+            return next;
+        });
+        return existed;
+    }
+    async read() {
+        try {
+            const parsed = JSON.parse(await readFile(this.filePath, 'utf8'));
+            if (!isSecretsFile(parsed))
+                return {};
+            return parsed.secrets;
+        }
+        catch {
+            // No file yet, or one this version cannot read: no secrets stored.
+            return {};
+        }
+    }
+    async update(change) {
+        this.writeQueue = this.writeQueue.then(async () => {
+            const secrets = change(await this.read());
+            const snapshot = { version: SCHEMA_VERSION, secrets };
+            await mkdir(dirname(this.filePath), { recursive: true });
+            if (Object.keys(secrets).length === 0) {
+                // Nothing left to keep: remove the file rather than leaving an empty
+                // one behind, so "no key stored" looks the same as never having one.
+                await unlink(this.filePath).catch(() => undefined);
+                return;
+            }
+            const temp = join(dirname(this.filePath), `.secrets.tmp-${process.pid}-${randomUUID()}`);
+            // 0600, and written whole then renamed, so a crash cannot leave a
+            // half-written key behind for the next read to find.
+            await writeFile(temp, JSON.stringify(snapshot, null, 2), { encoding: 'utf8', mode: 0o600 });
+            try {
+                await rename(temp, this.filePath);
+            }
+            catch (error) {
+                // The temp file holds the same ciphertext under the same 0600 as the
+                // destination, so this is tidiness rather than a leak — but an orphan
+                // per failed write, each with a key the user may since have rotated,
+                // is not something to leave lying around.
+                await unlink(temp).catch(() => undefined);
+                throw error;
+            }
+        });
+        await this.writeQueue;
+    }
+}
+function isSecretsFile(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const file = value;
+    if (file.version !== SCHEMA_VERSION)
+        return false;
+    if (typeof file.secrets !== 'object' || file.secrets === null)
+        return false;
+    return Object.values(file.secrets).every((entry) => typeof entry === 'string');
+}
+export function defaultSecretsPath(userDataPath) {
+    return join(userDataPath, 'secrets.json');
+}
+/** The name the speech server key is stored under. */
+export const SPEECH_API_KEY = 'speech.serverApiKey';
+/**
+ * The name the AI endpoint key is stored under.
+ *
+ * Separate from the speech key: the two point at different services often
+ * enough — a local Ollama and a hosted transcription server, say — that sharing
+ * one key would be wrong more often than right.
+ */
+export const AI_API_KEY = 'ai.serverApiKey';

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

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
-import { defaultShellBackend, findOpenSshTool, isLocalShellBackend, resolveShellBackend } from './shell-catalog.js';
+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}$/;
@@ -136,6 +136,14 @@ function loadPty() {
 export class ScreenService {
     ptys = new Map();
     sshSessions = new Map();
+    /**
+     * The argv each fallback local session was started with.
+     *
+     * Held apart from SessionInfo because it is not session metadata anyone else
+     * needs, and because the reported cwd moves as the shell does — a reattach
+     * must not rebuild the arguments from a directory that has since changed.
+     */
+    launchArgs = new Map();
     fallbackLocalSessions = new Map();
     onEvent;
     /** Injectable so tests can exercise routing and teardown without a real shell. */
@@ -195,14 +203,20 @@ export class ScreenService {
             ? resolveShellBackend(request.backend, request.wslDistribution)
             : defaultShellBackend();
         const backend = shell.backend;
-        const requestedCwd = request.cwd ?? homedir();
+        // A WSL shell starts where its own `--cd` argument says, not where the pty
+        // was launched from, so its directory is a Linux path inside the distro
+        // rather than the Windows one this side would otherwise report. Every other
+        // backend does start where the pty does.
+        const requestedCwd = request.cwd ?? (backend === 'wsl' ? WSL_HOME : homedir());
+        const launch = request.cwd ? withWslStartDirectory(shell, request.cwd) : shell;
         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);
+            this.launchArgs.set(fallback.id, launch.args);
             this.onEvent?.('created', fallback, true);
             return fallback;
         }
-        await execFileAsync('screen', ['-dmS', safeName, shell.executable, ...shell.args], { cwd: requestedCwd });
+        await execFileAsync('screen', ['-dmS', safeName, launch.executable, ...launch.args], { cwd: ptyStartDirectory(requestedCwd) });
         const session = { id: `local:${safeName}`, name: safeName, kind: 'local', host: 'local', cwd: requestedCwd, status: 'detached', lastSeen: new Date().toISOString(), persistence: 'screen', backend: 'screen', scope: 'local', source: 'active', screenName: safeName, wslDistribution: shell.wslDistribution };
         this.onEvent?.('created', session, true);
         return session;
@@ -252,7 +266,10 @@ export class ScreenService {
                 const shell = isLocalShellBackend(fallback.backend)
                     ? resolveShellBackend(fallback.backend, fallback.wslDistribution)
                     : defaultShellBackend();
-                this.spawnCommand(id, shell.executable, shell.args, onData, onExit, fallback.cwd, size);
+                // The arguments this session was created with, so a WSL pane reattaches
+                // to the same directory rather than losing its `--cd`.
+                const args = this.launchArgs.get(id) ?? shell.args;
+                this.spawnCommand(id, shell.executable, args, onData, onExit, ptyStartDirectory(fallback.cwd), size);
                 this.onEvent?.('attached', fallback, true);
                 return { ...fallback };
             }
@@ -384,6 +401,7 @@ export class ScreenService {
         this.detach(sessionId);
         this.sshSessions.delete(sessionId);
         this.fallbackLocalSessions.delete(sessionId);
+        this.launchArgs.delete(sessionId);
         this.onEvent?.('closed', session, false);
     }
 }

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

@@ -15,8 +15,69 @@
 // 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';
+import { homedir } from 'node:os';
 /** 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}$/;
+/**
+ * Where a WSL shell should start.
+ *
+ * `wsl.exe` inherits the Windows directory it was launched from, so without this
+ * a new WSL pane opens in `/mnt/c/Users/<name>` — the Windows home seen through
+ * the mount, which is almost never where anyone wants to be working. `--cd`
+ * takes a Linux path, and `~` is the distro user's own home.
+ *
+ * Passed as a separate argv element, never through a shell, so the tilde reaches
+ * `wsl.exe` literally rather than being expanded on the way.
+ */
+export const WSL_HOME = '~';
+/**
+ * `--cd` needs WSL 0.51.2 or newer — Windows 11, or the Store build on Windows
+ * 10. On an older inbox WSL the flag is rejected and the pane shows that, which
+ * is visible rather than silent. Judged worth it: the flag is four years old,
+ * Windows 10 is out of support, and the alternative was a capability probe on
+ * every session for a configuration this project does not target.
+ */
+function wslStartArgs(startDirectory = WSL_HOME) {
+    return ['--cd', startDirectory];
+}
+/**
+ * Point a resolved WSL shell at a directory other than the distro's home.
+ *
+ * Kept separate from resolveShellBackend because that is also what a reattach
+ * uses, where the right answer is the home directory again — a fresh shell, not
+ * wherever the last one wandered to.
+ */
+export function withWslStartDirectory(shell, startDirectory) {
+    if (shell.backend !== 'wsl')
+        return shell;
+    const args = [...shell.args];
+    const at = args.indexOf('--cd');
+    if (at >= 0 && at + 1 < args.length)
+        args[at + 1] = startDirectory;
+    else
+        args.push(...wslStartArgs(startDirectory));
+    return { ...shell, args };
+}
+/**
+ * A directory a pty can actually be started in.
+ *
+ * A session reports the directory its *shell* is in, which for WSL is a path
+ * inside the distro — `~`, or `/home/name` once the shell says so. node-pty
+ * hands its cwd straight to the OS, and neither of those is a directory Windows
+ * can start a process in. Where the shell itself begins is settled by its
+ * arguments, so anything unusable here falls back to the home directory rather
+ * than failing the spawn.
+ */
+export function ptyStartDirectory(cwd, options = {}) {
+    const home = options.home ?? homedir();
+    if (!cwd)
+        return home;
+    const windows = (options.platform ?? process.platform) === 'win32';
+    const usable = windows
+        ? /^[A-Za-z]:[\\/]/.test(cwd) || cwd.startsWith('\\\\')
+        : cwd.startsWith('/');
+    return usable ? cwd : home;
+}
 const LOCAL_SHELL_BACKENDS = [
     'bash', 'zsh', 'fish', 'sh', 'powershell', 'pwsh', 'cmd', 'wsl'
 ];
@@ -155,7 +216,7 @@ function shellCandidates(windows) {
             { 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' },
+            { backend: 'wsl', label: 'WSL', command: 'wsl.exe', args: wslStartArgs() },
             // Git for Windows ships bash; useful, but not a login shell for the OS.
             { backend: 'bash', label: 'Git Bash', command: 'bash.exe' }
         ];
@@ -234,5 +295,5 @@ export function resolveShellBackend(backend, distribution, options = {}) {
     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 };
+    return { ...match, args: ['-d', trimmed, ...wslStartArgs()], label: `WSL · ${trimmed}`, wslDistribution: trimmed };
 }

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

@@ -2,6 +2,17 @@ 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}$/;
+/**
+ * Is this a hostname ZeroG will put in front of an SSH client?
+ *
+ * Exported so the port-forwarding side vets the far end of a tunnel by the same
+ * rule that vets a HostName here, rather than carrying a second copy of it that
+ * can drift. The leading-alphanumeric requirement is the load-bearing part: the
+ * value ends up in an argv element, and one starting with '-' reads as an option.
+ */
+export function isSshHostName(value) {
+    return HOST.test(value);
+}
 // 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).

package/dist/main/main/workspace-store.js

@@ -0,0 +1,213 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+const SCHEMA_VERSION = 1;
+const MAX_WORKSPACES = 32;
+const MAX_MEMBERS = 4;
+/**
+ * Main-process-only, best-effort workspace persistence.
+ *
+ * Never stores cwd, command arguments, or credentials — the same guarantee
+ * SessionHistoryStore makes, and for the same reason: this file sits in plain
+ * JSON in the user's profile.
+ */
+export class WorkspaceStore {
+    filePath;
+    file = { version: SCHEMA_VERSION, workspaces: [] };
+    loaded = false;
+    writeQueue = Promise.resolve();
+    constructor(options) {
+        this.filePath = options.filePath;
+    }
+    async load() {
+        await this.ensureLoaded();
+        return normalizeFile(this.file) ?? { version: SCHEMA_VERSION, workspaces: [] };
+    }
+    async save(input) {
+        await this.ensureLoaded();
+        // Validate on the way in as well as out. The renderer is the only caller,
+        // but this is an IPC boundary and a stored bad value would come back on
+        // every launch from then on.
+        const normalized = normalizeFile(input);
+        if (!normalized)
+            throw new Error('Invalid workspace layout.');
+        this.file = normalized;
+        await this.persist();
+        return normalized;
+    }
+    async ensureLoaded() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const parsed = JSON.parse(await readFile(this.filePath, 'utf8'));
+            const normalized = normalizeFile(parsed);
+            if (normalized)
+                this.file = normalized;
+        }
+        catch {
+            // Missing, unreadable, or corrupt: start from an empty set rather than
+            // leaving the app unable to open a window.
+            this.file = { version: SCHEMA_VERSION, workspaces: [] };
+        }
+    }
+    async persist() {
+        const snapshot = this.file;
+        this.writeQueue = this.writeQueue.then(async () => {
+            try {
+                await mkdir(dirname(this.filePath), { recursive: true });
+                const temp = join(dirname(this.filePath), `.workspaces.tmp-${process.pid}-${randomUUID()}`);
+                await writeFile(temp, JSON.stringify(snapshot, null, 2), { encoding: 'utf8', mode: 0o600 });
+                await rename(temp, this.filePath);
+            }
+            catch {
+                // Layout memory must never affect terminal operation.
+            }
+        });
+        await this.writeQueue;
+    }
+}
+const LAYOUTS = ['stack', 'split-v', 'split-h', 'grid'];
+const SPLITS = ['split-v', 'split-h', 'grid'];
+/** Strip control characters and cap length; the file is user-editable. */
+function safeText(value, limit = 256) {
+    return value.replace(/[\u0000-\u001f\u007f]/g, '').slice(0, limit);
+}
+function optionalText(value, limit = 256) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = safeText(value, limit);
+    return text ? text : undefined;
+}
+function normalizeMember(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    if (typeof item.sessionId !== 'string' || typeof item.name !== 'string')
+        return undefined;
+    if (item.kind !== 'local' && item.kind !== 'ssh')
+        return undefined;
+    const sessionId = safeText(item.sessionId);
+    const name = safeText(item.name, 64);
+    if (!sessionId || !name)
+        return undefined;
+    const member = { sessionId, kind: item.kind, name };
+    const host = optionalText(item.host);
+    const screenName = optionalText(item.screenName, 64);
+    const sshTarget = optionalText(item.sshTarget);
+    const backend = optionalText(item.backend, 32);
+    if (host)
+        member.host = host;
+    if (screenName)
+        member.screenName = screenName;
+    if (sshTarget)
+        member.sshTarget = sshTarget;
+    if (backend)
+        member.backend = backend;
+    return member;
+}
+function normalizeView(value, memberIds) {
+    const item = (value && typeof value === 'object' ? value : {});
+    const layout = typeof item.layout === 'string' && LAYOUTS.includes(item.layout) ? item.layout : 'stack';
+    const lastSplit = typeof item.lastSplit === 'string' && SPLITS.includes(item.lastSplit) ? item.lastSplit : 'split-v';
+    // A view may only name sessions the workspace actually holds, so a hand-edited
+    // file cannot point a pane at something that is not there.
+    const member = (candidate) => {
+        const text = optionalText(candidate);
+        return text && memberIds.has(text) ? text : undefined;
+    };
+    const view = { layout, lastSplit, maximizedSessionId: member(item.maximizedSessionId) ?? null };
+    const active = member(item.activeSessionId);
+    const focused = member(item.focusedSessionId);
+    if (active)
+        view.activeSessionId = active;
+    if (focused)
+        view.focusedSessionId = focused;
+    const browsers = normalizeBrowsers(item.browsers, memberIds);
+    if (browsers)
+        view.browsers = browsers;
+    return view;
+}
+/**
+ * Directory browser state, keyed only by panes the workspace holds.
+ *
+ * The same rule the pane references above follow: a hand-edited file may not
+ * carry state for a session this workspace does not own. A malformed entry is
+ * dropped rather than repaired — a pane with no entry shows no browser, which is
+ * the safe reading of a file we cannot trust.
+ */
+function normalizeBrowsers(value, memberIds) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [id, raw] of Object.entries(value)) {
+        if (!memberIds.has(id) || !raw || typeof raw !== 'object')
+            continue;
+        const entry = raw;
+        if (typeof entry.open !== 'boolean')
+            continue;
+        const ratio = typeof entry.ratio === 'number' && Number.isFinite(entry.ratio) && entry.ratio > 0 && entry.ratio < 100
+            ? entry.ratio
+            : undefined;
+        out[id] = ratio === undefined ? { open: entry.open } : { open: entry.open, ratio };
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+function normalizeWorkspace(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    if (typeof item.id !== 'string' || typeof item.name !== 'string')
+        return undefined;
+    const id = safeText(item.id, 64);
+    const name = safeText(item.name, 64);
+    if (!id || !name)
+        return undefined;
+    const rawMembers = Array.isArray(item.members) ? item.members : [];
+    const members = [];
+    const seen = new Set();
+    for (const raw of rawMembers) {
+        const member = normalizeMember(raw);
+        // One pane per session: a duplicated id would render the same terminal
+        // twice and the two panes would fight over the pty size.
+        if (!member || seen.has(member.sessionId))
+            continue;
+        seen.add(member.sessionId);
+        members.push(member);
+        if (members.length >= MAX_MEMBERS)
+            break;
+    }
+    return { id, name, members, view: normalizeView(item.view, seen) };
+}
+export function normalizeFile(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const item = value;
+    if (item.version !== SCHEMA_VERSION)
+        return undefined;
+    if (!Array.isArray(item.workspaces))
+        return undefined;
+    const workspaces = [];
+    const seen = new Set();
+    for (const raw of item.workspaces) {
+        const workspace = normalizeWorkspace(raw);
+        if (!workspace || seen.has(workspace.id))
+            continue;
+        seen.add(workspace.id);
+        workspaces.push(workspace);
+        if (workspaces.length >= MAX_WORKSPACES)
+            break;
+    }
+    const file = { version: SCHEMA_VERSION, workspaces };
+    // An active id naming nothing would leave the app with no workspace on
+    // screen, so it falls back to the first rather than being kept.
+    const active = optionalText(item.activeWorkspaceId, 64);
+    if (active && seen.has(active))
+        file.activeWorkspaceId = active;
+    else if (workspaces.length)
+        file.activeWorkspaceId = workspaces[0].id;
+    return file;
+}
+export function defaultWorkspacePath(userDataPath) {
+    return join(userDataPath, 'workspaces.json');
+}

package/dist/main/main/wsl-home.js

@@ -0,0 +1,62 @@
+// What "~" means inside a WSL distribution.
+//
+// A WSL pane's shell reports its directory as `~` unless shell integration is
+// installed, and `~` is a symbol rather than a path: it cannot be turned into
+// the `\wsl.localhost\...` share path a listing needs. Asking the distro is the
+// only way to find out, and it is asked once per distribution and cached.
+//
+// Deliberately not done by typing `pwd` into the user's pane. That would put a
+// command they did not run into their shell history, which is the rule
+// cwd-tracker.ts states and keeps. This is a separate, short-lived process.
+import { execFile } from 'node:child_process';
+/**
+ * Distribution names, as they arrive from a session record.
+ *
+ * The first character must be alphanumeric: a name beginning with a dash would
+ * be read by `wsl.exe` as another option rather than as the distribution, and
+ * nothing that reaches an argv list should be able to become a flag.
+ */
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * The home directory out of the command's output.
+ *
+ * Anything that is not a single absolute POSIX path is rejected rather than
+ * repaired: this value becomes part of a path that is listed, and a distro that
+ * answered something surprising is a distro to give up on.
+ */
+export function parseWslHome(output) {
+    const text = output.trim();
+    if (!text || text.length > 4096)
+        return null;
+    if (!text.startsWith('/'))
+        return null;
+    if (/[\r\n\0]/.test(text))
+        return null;
+    return text;
+}
+/**
+ * Ask a distribution where its home directory is.
+ *
+ * Null on anything unexpected — a distro that is not installed, a name this
+ * process will not pass on, a slow or silent answer. The caller shows the pane's
+ * "not said where it is yet" state, which is the honest outcome.
+ */
+export async function wslHomeDirectory(distribution, run = execFile) {
+    if (!NAME.test(distribution))
+        return null;
+    return new Promise((resolve) => {
+        // argv, so the distribution name is an argument rather than part of a
+        // command line. `printf %s` rather than `echo` because it adds no newline
+        // and has no flags to be confused by a path.
+        const child = run('wsl.exe', ['-d', distribution, '--', 'sh', '-c', 'printf %s "$HOME"'], { timeout: 5000, windowsHide: true }, (error, stdout) => {
+            if (error) {
+                resolve(null);
+                return;
+            }
+            // WSL writes UTF-16 in some configurations; the NULs that leaves are
+            // stripped rather than treated as a malformed answer.
+            resolve(parseWslHome(String(stdout).split('\0').join('')));
+        });
+        child.on('error', () => resolve(null));
+    });
+}

package/dist/main/shared/endpoints.js

@@ -0,0 +1,73 @@
+// What counts as an endpoint ZeroG will make a request to, and what is worth
+// saying about one before it is used.
+//
+// Shared rather than owned by the speech side because the AI suggestion path now
+// asks the same three questions of the same kind of URL, and the answers must
+// match: a settings panel that warns a key travels in the clear for one feature
+// and not the other would be worse than either behaviour on its own.
+//
+// The host is the operator's choice — loopback, the LAN, or a hosted service —
+// and nothing here refuses one on that basis. What is enforced is the shape: an
+// http(s) URL with a host, so a typo or a file:// path cannot become a request.
+// See SECURITY.md.
+const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+/** The endpoint as a URL, or null when it is not one a request can be made to. */
+export function endpointOf(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        // http and https are special schemes, so a missing host is a parse failure
+        // rather than an empty hostname — every spelling of `http://` throws above.
+        // The check is kept anyway: this is the one gate before a request is made,
+        // and it should not rest on a parser detail holding everywhere.
+        if (!parsed.hostname)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function hostnameOf(url) {
+    const parsed = endpointOf(url);
+    return parsed === null ? null : parsed.hostname.toLowerCase();
+}
+/**
+ * Can a request be made to this URL?
+ *
+ * Any reachable host is allowed — loopback, LAN, or the public internet — but it
+ * has to be an http(s) URL naming a host. A `file://` path, a `ws://` URL or a
+ * half-typed address is refused here rather than turning into a request that
+ * fails obscurely later.
+ */
+export function isSupportedEndpoint(url) {
+    return hostnameOf(url) !== null;
+}
+/**
+ * Does this endpoint keep the payload on this machine?
+ *
+ * Nothing is refused on this basis; the settings panel uses it to say plainly
+ * when recorded speech or terminal output is about to leave the machine.
+ * `*.localhost` resolves to loopback by specification, so it counts.
+ */
+export function isLoopbackEndpoint(url) {
+    const hostname = hostnameOf(url);
+    if (hostname === null)
+        return false;
+    return LOOPBACK_HOSTNAMES.has(hostname) || hostname.endsWith('.localhost');
+}
+/**
+ * Would a key sent to this endpoint travel in the clear?
+ *
+ * True for plain http to anywhere but this machine. Nothing is blocked on this
+ * basis — a self-hosted server on the LAN commonly has no certificate, and
+ * refusing to authenticate to it would break the ordinary case — but it is worth
+ * saying out loud next to the field where the key is typed.
+ */
+export function sendsKeyInClear(url) {
+    const parsed = endpointOf(url);
+    if (parsed === null)
+        return false;
+    return parsed.protocol === 'http:' && !isLoopbackEndpoint(url);
+}