@shardflux/cli 0.19.1 → 0.22.0

package/dist/terminal-apps.js

@@ -0,0 +1,561 @@
+/**
+ * The terminal app conversations open in (0.20.1+): chosen once (`terminal_app` in agents.json, written by
+ * `shard agents targets --terminal <app>[:tab|:window]`), a tab in its front window by default. One launcher serves
+ * every client: `shard agents open <ref> --in terminal`, `shard ./` from a coding agent's shell, the macOS menu bar and
+ * the Linux desktop (`shard agents terminal-run`, hidden).
+ *
+ * macOS: Ghostty 1.3+ and iTerm2 by AppleScript (a tab in the front window, or a window), Terminal.app by AppleScript (a
+ * window), WezTerm and kitty by their remote-control CLIs, Alacritty with `alacritty msg` (a window), Warp with a tab
+ * config and its warp:// link. Linux: the same CLIs and `ghostty +new-window`, then $TERMINAL, x-terminal-emulator and
+ * gnome-terminal. When the chosen app is missing or refuses, the next running terminal opens it, then Terminal.app (or
+ * the Linux default), and the reason is said in one line.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+import { codingAgentShell } from "./agent-setup.js";
+import { applicationDirs } from "./agent-targets.js";
+import { UsageError } from "./errors.js";
+import { linuxTerminalCommand } from "./linux-terminal.js";
+export const TERMINAL_IDS = ['ghostty', 'iterm', 'terminal', 'wezterm', 'kitty', 'alacritty', 'warp'];
+const SPECS = {
+    ghostty: { name: 'Ghostty', bundle: 'com.mitchellh.ghostty', app: 'Ghostty.app', termProgram: ['ghostty'], tabs: { darwin: true, linux: false }, linux: ['ghostty'] },
+    iterm: { name: 'iTerm2', bundle: 'com.googlecode.iterm2', app: 'iTerm.app', termProgram: ['iTerm.app'], tabs: { darwin: true, linux: false }, linux: [] },
+    terminal: { name: 'Terminal', bundle: 'com.apple.Terminal', app: 'Terminal.app', termProgram: ['Apple_Terminal'], tabs: { darwin: false, linux: false }, linux: [] },
+    wezterm: { name: 'WezTerm', bundle: 'com.github.wez.wezterm', app: 'WezTerm.app', termProgram: ['WezTerm'], tabs: { darwin: true, linux: true }, linux: ['wezterm'] },
+    kitty: { name: 'kitty', bundle: 'net.kovidgoyal.kitty', app: 'kitty.app', tabs: { darwin: true, linux: true }, linux: ['kitty'] },
+    alacritty: { name: 'Alacritty', bundle: 'org.alacritty', app: 'Alacritty.app', tabs: { darwin: false, linux: false }, linux: ['alacritty'] },
+    warp: { name: 'Warp', bundle: 'dev.warp.Warp-Stable', app: 'Warp.app', termProgram: ['WarpTerminal'], tabs: { darwin: true, linux: true }, linux: ['warp-terminal'] },
+};
+export const terminalName = (id) => SPECS[id].name;
+const isId = (v) => typeof v === 'string' && TERMINAL_IDS.includes(v);
+/** The terminals this platform can open conversations in (iTerm2 is macOS only). */
+export const platformTerminals = (platform = process.platform) => platform === 'darwin' ? [...TERMINAL_IDS] : platform === 'linux' ? TERMINAL_IDS.filter(id => id !== 'iterm') : [];
+export const tabSupported = (id, platform = process.platform) => platform === 'darwin' ? SPECS[id].tabs.darwin : SPECS[id].tabs.linux;
+/** Native lookups and launches; tests replace them (no osascript, no terminal ever starts in a test). */
+export const terminalNative = {
+    /** A short program's result; `code` is null when it did not start or ran out of time. */
+    run(command, args, opts) {
+        return new Promise(resolve => {
+            let stdout = '', stderr = '', done = false;
+            const finish = (code) => { if (!done) {
+                done = true;
+                clearTimeout(timer);
+                resolve({ code, stdout, stderr });
+            } };
+            let child;
+            try {
+                child = spawn(command, args, { env: opts.env, cwd: opts.cwd, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
+            }
+            catch (error) {
+                resolve({ code: null, stdout: '', stderr: String(error) });
+                return;
+            }
+            const timer = setTimeout(() => { child.kill('SIGKILL'); stderr ||= `${basename(command)} did not answer in time`; finish(null); }, opts.timeoutMs ?? 15_000);
+            child.stdout?.on('data', (c) => { stdout += c.toString(); });
+            child.stderr?.on('data', (c) => { stderr += c.toString(); });
+            child.once('error', e => { stderr ||= e.message; finish(null); });
+            child.once('close', code => finish(code));
+            // A program that exits without reading its input (a refusal) must not fail this one with EPIPE.
+            child.stdin?.on('error', () => undefined);
+            if (opts.input !== undefined)
+                child.stdin?.end(opts.input);
+        });
+    },
+    /** Starts a program that outlives shard (a new terminal window): true once it started. */
+    start(command, args, opts) {
+        return new Promise(resolve => {
+            let child;
+            try {
+                child = spawn(command, args, { env: opts.env, cwd: opts.cwd, detached: true, stdio: 'ignore' });
+            }
+            catch {
+                resolve(false);
+                return;
+            }
+            child.once('spawn', () => { child.unref(); resolve(true); });
+            child.once('error', () => resolve(false));
+        });
+    },
+    /** Running processes: executable paths on macOS, program names on Linux (one `ps`). */
+    processes(env) {
+        const r = spawnSync(process.platform === 'darwin' ? '/bin/ps' : 'ps', ['-Ao', 'comm='], { env, encoding: 'utf8', input: '', timeout: 2000 });
+        return r.status === 0 ? r.stdout.split('\n').map(l => l.trim()).filter(Boolean) : [];
+    },
+    /** App bundles with these bundle ids anywhere Spotlight knows (macOS), one query. */
+    spotlight(bundles, env) {
+        if (!bundles.length)
+            return [];
+        const query = bundles.map(b => `kMDItemCFBundleIdentifier == '${b}'`).join(' || ');
+        const r = spawnSync('/usr/bin/mdfind', [query], { env, encoding: 'utf8', input: '', timeout: 2000 });
+        return r.status === 0 ? r.stdout.split('\n').map(l => l.trim()).filter(p => p.endsWith('.app')) : [];
+    },
+    /** CFBundleShortVersionString of an app bundle. */
+    appVersion(path) {
+        const r = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleShortVersionString', join(path, 'Contents', 'Info.plist')], { encoding: 'utf8', input: '', timeout: 1000 });
+        return r.status === 0 ? r.stdout.trim() || null : null;
+    },
+    writeFile(file, text) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, text, { mode: 0o600 }); },
+};
+const bundleIs = (path, bundle) => {
+    try {
+        return readFileSync(join(path, 'Contents', 'Info.plist')).includes(bundle);
+    }
+    catch {
+        return false;
+    }
+};
+const onPath = (name, env) => {
+    for (const dir of (env.PATH ?? '').split(':').filter(Boolean)) {
+        const file = join(dir, name);
+        try {
+            accessSync(file, constants.X_OK);
+            if (statSync(file).isFile())
+                return file;
+        }
+        catch { /* next */ }
+    }
+    return null;
+};
+/**
+ * The terminals this platform can use, installed or not. macOS: app bundles in the app folders (applicationDirs, and
+ * the system's Utilities folder) and, with `spotlight`, anywhere Spotlight finds their bundle ids; Terminal.app is part
+ * of macOS. SHARDFLUX_APPLICATIONS_DIRS (tests) replaces every folder and turns Spotlight off. Linux: programs on PATH;
+ * `terminal` is the default terminal ($TERMINAL, x-terminal-emulator, gnome-terminal).
+ */
+export function detectTerminals(env, platform = process.platform, opts = {}) {
+    const ids = platformTerminals(platform);
+    if (!ids.length)
+        return [];
+    const paths = {};
+    if (platform === 'darwin') {
+        const custom = env.SHARDFLUX_APPLICATIONS_DIRS !== undefined;
+        const dirs = [...applicationDirs(env, platform), ...(custom ? [] : ['/Applications/Utilities', '/System/Applications/Utilities'])];
+        for (const id of ids) {
+            const { app, bundle } = SPECS[id];
+            const found = dirs.map(d => join(d, app)).find(p => bundleIs(p, bundle));
+            if (found)
+                paths[id] = found;
+        }
+        const missing = ids.filter(id => !paths[id]);
+        if (!custom && opts.spotlight && missing.length) {
+            for (const path of terminalNative.spotlight(missing.map(id => SPECS[id].bundle), env)) {
+                const id = missing.find(m => !paths[m] && bundleIs(path, SPECS[m].bundle));
+                if (id)
+                    paths[id] = path;
+            }
+        }
+        if (!paths.terminal && !custom)
+            paths.terminal = '/System/Applications/Utilities/Terminal.app';
+    }
+    else {
+        for (const id of ids) {
+            if (id === 'terminal') {
+                const choice = linuxTerminalCommand(['true'], env);
+                if (choice)
+                    paths.terminal = onPath(choice.command, env) ?? choice.command;
+                continue;
+            }
+            const found = SPECS[id].linux.map(name => onPath(name, env)).find(Boolean);
+            if (found)
+                paths[id] = found;
+        }
+    }
+    const procs = ids.some(id => paths[id]) ? terminalNative.processes(env) : [];
+    const running = (id) => {
+        const path = paths[id];
+        if (!path)
+            return false;
+        if (platform === 'darwin')
+            return procs.some(p => p.startsWith(`${path}/Contents/MacOS/`));
+        const names = id === 'wezterm' ? ['wezterm-gui', 'wezterm'] : id === 'warp' ? ['warp-terminal', 'warp'] : id === 'terminal' ? [] : [basename(path)];
+        return procs.some(p => names.includes(basename(p)));
+    };
+    return ids.map(id => ({ id, name: SPECS[id].name, installed: !!paths[id], running: running(id), tab_supported: tabSupported(id, platform), path: paths[id] ?? null }));
+}
+/** The terminal a command runs in: TERM_PROGRAM, the terminals' own variables, then the app that started it. */
+export function currentTerminal(env) {
+    const program = env.TERM_PROGRAM;
+    const byProgram = TERMINAL_IDS.find(id => program && SPECS[id].termProgram?.includes(program));
+    if (byProgram)
+        return byProgram;
+    if (env.KITTY_WINDOW_ID || env.TERM === 'xterm-kitty')
+        return 'kitty';
+    if (env.ALACRITTY_WINDOW_ID || env.ALACRITTY_SOCKET || env.TERM === 'alacritty')
+        return 'alacritty';
+    if (env.GHOSTTY_RESOURCES_DIR || env.TERM === 'xterm-ghostty')
+        return 'ghostty';
+    if (env.WEZTERM_PANE)
+        return 'wezterm';
+    if (env.ITERM_SESSION_ID)
+        return 'iterm';
+    return TERMINAL_IDS.find(id => env.__CFBundleIdentifier && SPECS[id].bundle === env.__CFBundleIdentifier) ?? null;
+}
+/** The choice saved with `agents targets --terminal`, or null (auto). */
+export function storedTerminal(dir) {
+    const value = new AgentStateStore(dir).read().terminal_app;
+    if (!value || typeof value !== 'object' || !isId(value.id))
+        return null;
+    return { id: value.id, mode: value.mode === 'window' ? 'window' : 'tab' };
+}
+/**
+ * `--terminal <app>[:tab|:window]` checked against this computer: null for `auto` (clears the choice). A terminal that
+ * opens only windows takes `<app>` or `<app>:window`; without a mode, a tab where the app opens tabs.
+ */
+export function parseTerminalChoice(spec, terminals, platform = process.platform) {
+    const [raw = '', mode, extra] = spec.trim().toLowerCase().split(':');
+    const id = raw === 'iterm2' ? 'iterm' : raw === 'apple-terminal' ? 'terminal' : raw;
+    if (id === 'auto' && mode === undefined)
+        return null;
+    const known = platformTerminals(platform);
+    if (!isId(id) || !known.includes(id) || extra !== undefined || (mode !== undefined && mode !== 'tab' && mode !== 'window')) {
+        throw new UsageError(`--terminal takes ${known.join(', ')} or auto, optionally with :tab or :window (e.g. ghostty:tab).`);
+    }
+    const info = terminals.find(t => t.id === id);
+    if (!info?.installed) {
+        const installed = terminals.filter(t => t.installed).map(t => t.id);
+        throw new UsageError(`--terminal: ${SPECS[id].name} is not installed on this computer${installed.length ? `; installed: ${installed.join(', ')}` : ''}.`);
+    }
+    if (mode === 'tab' && !info.tab_supported)
+        throw new UsageError(`--terminal: ${SPECS[id].name} opens each conversation in a new window; use ${id} or ${id}:window.`);
+    return { id, mode: mode ?? (info.tab_supported ? 'tab' : 'window') };
+}
+export function saveTerminalChoice(dir, choice) {
+    new AgentStateStore(dir).update(doc => { if (choice)
+        doc.terminal_app = choice;
+    else
+        delete doc.terminal_app; });
+}
+/** Where a terminal conversation opens now: the saved choice while installed, else the terminal this runs in, else a
+ * running terminal, else Terminal.app (macOS) or the default terminal (Linux). null when the computer has none. */
+export function effectiveTerminal(stored, terminals, env) {
+    const installed = (id) => id ? terminals.find(t => t.id === id && t.installed) : undefined;
+    const saved = installed(stored?.id);
+    if (stored && saved)
+        return { id: stored.id, mode: saved.tab_supported ? stored.mode : 'window', saved: true };
+    const pick = installed(currentTerminal(env)) ?? terminals.find(t => t.installed && t.running && t.id !== 'terminal') ?? installed('terminal');
+    return pick ? { id: pick.id, mode: pick.tab_supported ? 'tab' : 'window', saved: false } : null;
+}
+/** The terminal part of `agents targets --json` (0.20.1+). */
+export function terminalReport(dir, env, terminals) {
+    const stored = storedTerminal(dir);
+    const current = currentTerminal(env);
+    const effective = effectiveTerminal(stored, terminals, env);
+    return {
+        terminal_app: stored,
+        terminal: effective ? { ...effective, name: SPECS[effective.id].name } : null,
+        current_terminal: current && terminals.some(t => t.id === current) ? current : null,
+        terminals: terminals.map(({ id, name, installed, running, tab_supported, path }) => ({ id, name, installed, running, tab_supported, path })),
+    };
+}
+// ── The launcher ────────────────────────────────────────────────────────────────────────────────────────────────────
+const BARE_WORD = /^[A-Za-z0-9_@%+=:,./-]+$/;
+/** A shell word, quoted only when it needs it (the line shows in the person's terminal). */
+export const shellWord = (s) => s && BARE_WORD.test(s) ? s : `'${s.replaceAll("'", "'\\''")}'`;
+/** The command as typed: with this computer's config folder when it is not the default (an app's own, a test's). */
+export function commandLine(argv, env) {
+    return `${env.SHARDFLUX_CONFIG_DIR ? `env SHARDFLUX_CONFIG_DIR=${shellWord(env.SHARDFLUX_CONFIG_DIR)} ` : ''}${argv.map(shellWord).join(' ')}`;
+}
+/** What a shell in a new tab types: into the project folder, then the command. */
+export const typedLine = (argv, cwd, env) => `cd ${shellWord(cwd)} && ${commandLine(argv, env)}`;
+/** A new window's own command (Linux, Alacritty): it keeps the window open on an error so the person can read it. */
+export function windowCommand(argv, cwd, env) {
+    return ['sh', '-c', `cd ${shellWord(cwd)} 2>/dev/null; ${commandLine(argv, env)}; status=$?; if [ "$status" -ne 0 ]; then printf '\\nPress Enter to close.'; read answer; fi; exit "$status"`];
+}
+/** An AppleScript string literal. */
+export const appleString = (s) => `"${s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n').replaceAll('\r', '\\r')}"`;
+/**
+ * The AppleScript that opens `command` in `cwd` in a new shell of Ghostty, iTerm2 or Terminal.app. A tab goes in the
+ * front window; with no window, or `window`, a new window. An app this script starts uses the window it opens with.
+ */
+export function appleScript(id, mode, command, cwd) {
+    const typed = appleString(`cd ${shellWord(cwd)} && ${command}`);
+    if (id === 'ghostty') {
+        // Ghostty 1.3+: a surface configuration carries the folder; the command is typed into the new tab's shell.
+        const run = (t) => [`set t to focused terminal of ${t}`, `input text ${appleString(command)} to t`, 'send key "enter" to t'];
+        const cfg = ['set cfg to new surface configuration', `set initial working directory of cfg to ${appleString(cwd)}`];
+        const lines = mode === 'window'
+            ? [...cfg, ...run('selected tab of (new window with configuration cfg)')]
+            : ['if not wasRunning and (count of windows) > 0 then', `    set t to focused terminal of selected tab of front window`, `    input text ${typed} to t`, '    send key "enter" to t',
+                'else', ...cfg.map(l => `    ${l}`), '    if (count of windows) is 0 then', ...run('selected tab of (new window with configuration cfg)').map(l => `        ${l}`),
+                '    else', ...run('(new tab in front window with configuration cfg)').map(l => `        ${l}`), '    end if', 'end if'];
+        return ['set wasRunning to application id "com.mitchellh.ghostty" is running', 'tell application id "com.mitchellh.ghostty"', '    activate',
+            ...lines.map(l => `    ${l}`), 'end tell'].join('\n');
+    }
+    if (id === 'iterm') {
+        const window = `tell current session of (create window with default profile) to write text ${typed}`;
+        const lines = mode === 'window' ? [window]
+            : ['if (count of windows) is 0 then', `    ${window}`, 'else if not wasRunning then', `    tell current session of current window to write text ${typed}`, 'else',
+                `    tell current window to tell current session of (create tab with default profile) to write text ${typed}`, 'end if'];
+        return ['set wasRunning to application id "com.googlecode.iterm2" is running', 'tell application id "com.googlecode.iterm2"', '    activate',
+            ...lines.map(l => `    ${l}`), 'end tell'].join('\n');
+    }
+    return ['tell application id "com.apple.Terminal"', '    activate', `    do script ${typed}`, 'end tell'].join('\n');
+}
+/** Warp's tab config for one conversation (`warp://tab_config/shardflux`). */
+export function warpTabConfig(argv, cwd, env) {
+    return [
+        '# Written by Shardflux each time it opens a conversation in Warp.',
+        'name = "Shardflux conversation"',
+        '',
+        '[[panes]]',
+        'id = "conversation"',
+        'type = "terminal"',
+        `directory = ${JSON.stringify(cwd)}`,
+        `commands = [${JSON.stringify(commandLine(argv, env))}]`,
+        'is_focused = true',
+        '',
+    ].join('\n');
+}
+export function warpTabConfigFile(env, platform = process.platform) {
+    const home = env.HOME || homedir();
+    return platform === 'darwin' ? join(home, '.warp', 'tab_configs', 'shardflux.toml')
+        : join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'warp-terminal', 'tab_configs', 'shardflux.toml');
+}
+/** kitty's remote-control socket: KITTY_LISTEN_ON, else `listen_on` in kitty.conf (kitty adds -<pid> to a unix path). */
+export function kittySocket(env, platform = process.platform) {
+    if (env.KITTY_LISTEN_ON)
+        return env.KITTY_LISTEN_ON;
+    const home = env.HOME || homedir();
+    const files = [join(env.KITTY_CONFIG_DIRECTORY || join(env.XDG_CONFIG_HOME || join(home, '.config'), 'kitty'), 'kitty.conf'),
+        ...(platform === 'darwin' ? [join(home, 'Library', 'Preferences', 'kitty', 'kitty.conf')] : [])];
+    for (const file of files) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const value = [...text.matchAll(/^\s*listen_on\s+(\S+)/gm)].at(-1)?.[1];
+        if (!value)
+            continue;
+        if (!value.startsWith('unix:') || value.startsWith('unix:@'))
+            return value;
+        const path = value.slice(5).replace(/^~(?=\/)/, home);
+        if (existsSync(path))
+            return `unix:${path}`;
+        const prefix = basename(path.replace('{kitty_pid}', '')).replace(/-$/, '');
+        try {
+            const match = readdirSync(dirname(path)).filter(n => n.startsWith(`${prefix}-`)).map(n => join(dirname(path), n))
+                .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+            if (match)
+                return `unix:${match}`;
+        }
+        catch { /* no socket folder */ }
+    }
+    return null;
+}
+/** Who macOS asks to allow: the app this runs under (the menu bar, a terminal, the Claude or Codex app). */
+function requester(env) {
+    const bundle = env.__CFBundleIdentifier ?? '';
+    if (bundle.startsWith('dev.shardflux.'))
+        return 'Shardflux';
+    if (bundle === 'com.anthropic.claudefordesktop')
+        return 'Claude';
+    if (bundle === 'com.openai.codex')
+        return 'Codex';
+    const id = TERMINAL_IDS.find(t => SPECS[t].bundle === bundle) ?? currentTerminal(env);
+    return id ? SPECS[id].name : 'your terminal app';
+}
+const firstLine = (text) => text.trim().split('\n').at(-1)?.trim().slice(0, 200) ?? '';
+/** Opens it in one terminal: undefined once it opened, else the one-line reason. */
+async function openWith(t, mode, l) {
+    const { argv, cwd, env, platform } = l;
+    const line = typedLine(argv, cwd, env);
+    const name = t.name;
+    const command = commandLine(argv, env);
+    const mac = platform === 'darwin';
+    const activate = async () => { if (mac && t.path)
+        await terminalNative.run('/usr/bin/open', ['-a', t.path], { env, timeoutMs: 5000 }); };
+    const bin = (macName, linuxName) => mac ? (t.path ? join(t.path, 'Contents', 'MacOS', macName) : onPath(macName, env)) : onPath(linuxName, env);
+    if (mac && (t.id === 'ghostty' || t.id === 'iterm' || t.id === 'terminal')) {
+        if (t.id === 'ghostty' && t.path) {
+            const version = terminalNative.appVersion(t.path);
+            if (version && compareVersions(version, '1.3.0') < 0)
+                return `Ghostty ${version} can’t take commands from other apps; update Ghostty to 1.3 or later.`;
+        }
+        const r = await terminalNative.run('/usr/bin/osascript', ['-e', `with timeout of 20 seconds\n${appleScript(t.id, mode, command, cwd)}\nend timeout`], { env, timeoutMs: 25_000 });
+        if (r.code === 0)
+            return undefined;
+        if (/-1743|not authori[sz]ed|not allowed to send/i.test(r.stderr))
+            return `Allow ${requester(env)} to control ${name} in System Settings → Privacy & Security → Automation.`;
+        return `${name} didn’t open it${firstLine(r.stderr) ? `: ${firstLine(r.stderr)}` : ''}.`;
+    }
+    if (t.id === 'warp') {
+        const file = warpTabConfigFile(env, platform);
+        try {
+            terminalNative.writeFile(file, warpTabConfig(argv, cwd, env));
+        }
+        catch (error) {
+            return `Warp’s tab config could not be written: ${error.message}.`;
+        }
+        const r = await terminalNative.run(mac ? '/usr/bin/open' : 'xdg-open', [`warp://tab_config/shardflux${mode === 'window' ? '?new_window=true' : ''}`], { env, timeoutMs: 10_000 });
+        return r.code === 0 ? undefined : `Warp didn’t open its link${firstLine(r.stderr) ? `: ${firstLine(r.stderr)}` : ''}.`;
+    }
+    if (t.id === 'wezterm') {
+        const wezterm = bin('wezterm', 'wezterm');
+        if (!wezterm)
+            return 'WezTerm’s wezterm command was not found.';
+        const spawned = await terminalNative.run(wezterm, ['cli', 'spawn', ...(mode === 'window' ? ['--new-window'] : []), '--cwd', cwd], { env, timeoutMs: 10_000 });
+        const pane = spawned.stdout.trim();
+        if (spawned.code === 0 && /^\d+$/.test(pane)) {
+            const sent = await terminalNative.run(wezterm, ['cli', 'send-text', '--pane-id', pane, '--no-paste'], { env, input: `${line}\r`, timeoutMs: 10_000 });
+            if (sent.code !== 0)
+                return `WezTerm didn’t take the command${firstLine(sent.stderr) ? `: ${firstLine(sent.stderr)}` : ''}.`;
+            await terminalNative.run(wezterm, ['cli', 'activate-pane', '--pane-id', pane], { env, timeoutMs: 5000 });
+            await activate();
+            return undefined;
+        }
+        if (!t.running && await terminalNative.start(wezterm, ['start', '--cwd', cwd, '--', ...windowCommand(argv, cwd, env)], { env, cwd }))
+            return undefined;
+        return `WezTerm didn’t open a tab${firstLine(spawned.stderr) ? `: ${firstLine(spawned.stderr)}` : ''}.`;
+    }
+    if (t.id === 'kitty') {
+        const kitten = bin('kitten', 'kitten'), kitty = bin('kitty', 'kitty');
+        const socket = kittySocket(env, platform);
+        if (kitten && socket) {
+            const launched = await terminalNative.run(kitten, ['@', '--to', socket, 'launch', `--type=${mode === 'tab' ? 'tab' : 'os-window'}`, `--cwd=${cwd}`], { env, timeoutMs: 10_000 });
+            const window = launched.stdout.trim();
+            if (launched.code === 0 && /^\d+$/.test(window)) {
+                const sent = await terminalNative.run(kitten, ['@', '--to', socket, 'send-text', `--match=id:${window}`, '--stdin'], { env, input: `${line}\r`, timeoutMs: 10_000 });
+                if (sent.code !== 0)
+                    return `kitty didn’t take the command${firstLine(sent.stderr) ? `: ${firstLine(sent.stderr)}` : ''}.`;
+                await activate();
+                return undefined;
+            }
+        }
+        if (!t.running && kitty && await terminalNative.start(kitty, ['--directory', cwd, ...windowCommand(argv, cwd, env)], { env, cwd }))
+            return undefined;
+        return 'Turn on remote control in kitty (allow_remote_control yes and listen_on unix:/tmp/kitty in kitty.conf), then restart kitty.';
+    }
+    if (t.id === 'alacritty') {
+        const alacritty = bin('alacritty', 'alacritty');
+        if (!alacritty)
+            return 'Alacritty’s alacritty command was not found.';
+        if (t.running) {
+            const r = await terminalNative.run(alacritty, ['msg', 'create-window', '--working-directory', cwd, '-e', ...windowCommand(argv, cwd, env)], { env, timeoutMs: 10_000 });
+            if (r.code === 0) {
+                await activate();
+                return undefined;
+            }
+            return `Alacritty didn’t open a window${firstLine(r.stderr) ? `: ${firstLine(r.stderr)}` : ''}.`;
+        }
+        return await terminalNative.start(alacritty, ['--working-directory', cwd, '-e', ...windowCommand(argv, cwd, env)], { env, cwd }) ? undefined : 'Alacritty did not start.';
+    }
+    if (t.id === 'ghostty') {
+        // Linux: a window in the running Ghostty over D-Bus (1.2+), else a new Ghostty.
+        const ghostty = onPath('ghostty', env);
+        if (!ghostty)
+            return 'Ghostty’s ghostty command was not found.';
+        const r = await terminalNative.run(ghostty, ['+new-window', '-e', ...windowCommand(argv, cwd, env)], { env, timeoutMs: 10_000 });
+        if (r.code === 0)
+            return undefined;
+        return await terminalNative.start(ghostty, [`--working-directory=${cwd}`, '-e', ...windowCommand(argv, cwd, env)], { env, cwd }) ? undefined : 'Ghostty did not start.';
+    }
+    // Linux's default terminal: $TERMINAL, x-terminal-emulator, gnome-terminal.
+    const choice = linuxTerminalCommand([...argv], env, cwd);
+    if (!choice)
+        return 'No terminal emulator was found ($TERMINAL, x-terminal-emulator or gnome-terminal).';
+    return await terminalNative.start(choice.command, choice.args, { env, cwd }) ? undefined : `${choice.command} did not start.`;
+}
+export function compareVersions(a, b) {
+    const pa = a.split(/[.-]/).map(n => Number.parseInt(n, 10) || 0), pb = b.split(/[.-]/).map(n => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++)
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) - (pb[i] ?? 0);
+    return 0;
+}
+/**
+ * Opens `argv` in the person's terminal app, in `cwd`: the chosen app (effectiveTerminal) as a tab, or a window with
+ * `window`; when it fails, the other running terminals, then Terminal.app or the Linux default terminal.
+ */
+export async function openInTerminal(dir, env, argv, opts) {
+    const platform = opts.platform ?? process.platform;
+    const stored = storedTerminal(dir);
+    let terminals = detectTerminals(env, platform);
+    if (stored && !terminals.find(t => t.id === stored.id)?.installed)
+        terminals = detectTerminals(env, platform, { spotlight: true });
+    const chosen = effectiveTerminal(stored, terminals, env);
+    const command = [...argv];
+    if (!chosen)
+        return { opened: false, app: null, mode: null, command, reason: platform === 'darwin' || platform === 'linux' ? 'No terminal app was found on this computer.' : 'Opening a terminal app needs macOS or Linux.' };
+    const order = [chosen.id, ...terminals.filter(t => t.installed && t.running && t.id !== 'terminal').map(t => t.id), 'terminal'];
+    let reason;
+    for (const id of [...new Set(order)]) {
+        const t = terminals.find(x => x.id === id && x.installed);
+        if (!t)
+            continue;
+        const mode = !t.tab_supported || opts.window ? 'window' : id === chosen.id ? chosen.mode : 'tab';
+        const failed = await openWith(t, mode, { argv, cwd: opts.cwd, env, platform });
+        if (!failed)
+            return { opened: true, app: id, mode, command, ...(id !== chosen.id ? { fallback_from: chosen.id, ...(reason ? { reason } : {}) } : {}) };
+        reason ??= failed;
+    }
+    return { opened: false, app: null, mode: null, command, ...(reason ? { reason } : {}) };
+}
+/** "Opened in Ghostty (new tab)." and, when it fell back, the reason on its own line. */
+export function openedText(result) {
+    if (!result.opened || !result.app)
+        return { line: '', ...(result.reason ? { note: result.reason } : {}) };
+    const line = `Opened in ${SPECS[result.app].name} (new ${result.mode}).`;
+    return result.fallback_from ? { line, note: `Not in ${SPECS[result.fallback_from].name}: ${result.reason ?? 'it did not open.'}` } : { line };
+}
+/** The runnable command that opens a conversation: this shard (an app's own Node.js and script) when it is not the
+ * `shard` on PATH, with its API. */
+export function shardArgv(runtime, apiUrl, words, env) {
+    if (runtime?.script && !sameFile(onPath('shard', env), runtime.script))
+        return [runtime.node, runtime.script, '--api-url', apiUrl, ...words];
+    return ['shard', '--api-url', apiUrl, ...words];
+}
+function sameFile(a, b) {
+    if (!a)
+        return false;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+// ── Commands ────────────────────────────────────────────────────────────────────────────────────────────────────────
+/** A terminal a person types into: not a pipe, and not a coding agent's shell (a PTY nobody types into, 0.17.1+). */
+export const attachable = (io) => io.stdin.isTTY === true && io.stdout.isTTY !== false && !codingAgentShell(io.env);
+/**
+ * The local folder a conversation or agent belongs to, where its terminal tab starts: the conversation's record, the
+ * Git agent's repository, else the current folder (the home folder for an app, whose folder is /).
+ */
+export function referenceFolder(dir, apiUrl, ref, env) {
+    const doc = new AgentStateStore(dir).read();
+    const conversations = (doc.conversations ?? {});
+    const repos = (doc.git_repositories ?? {});
+    const record = conversations[ref]?.api_url === apiUrl ? conversations[ref]
+        : Object.values(conversations).find(c => c.api_url === apiUrl && c.conversation?.key === ref);
+    const repo = Object.values(repos).find(r => Object.values(r.agents ?? {}).some(a => a.workspace_key === ref));
+    const isDir = (p) => { try {
+        return typeof p === 'string' && p.startsWith('/') && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    } };
+    const cwd = process.cwd();
+    return [record?.folder, repo?.root].find(isDir) ?? (cwd !== '/' ? cwd : env.HOME || homedir());
+}
+/** `--json`: `{target: 'terminal', opened, app, mode, command, fallback_from?, reason?}`; text: where it opened, the
+ * reason it fell back on stderr, and with nothing opened the runnable command. */
+export function reportTerminalOpen(ctx, result, extra = {}) {
+    if (ctx.json) {
+        ctx.io.stdout.write(`${JSON.stringify({ target: 'terminal', ...extra, ...result })}\n`);
+        return;
+    }
+    const text = openedText(result);
+    if (text.note)
+        ctx.io.stderr.write(`${text.note}\n`);
+    ctx.io.stdout.write(result.opened ? `${text.line}\n` : `${commandLine(result.command, ctx.io.env)}\n`);
+}
+/** Opens `shard <words>` (a conversation's attach) in the person's terminal app, in `cwd`. */
+export function openShardInTerminal(ctx, words, opts) {
+    return openInTerminal(ctx.store.dir, ctx.io.env, shardArgv(ctx.runtime, ctx.apiUrl, words, ctx.io.env), opts);
+}

package/dist/terminal-onboarding.d.ts

@@ -6,6 +6,8 @@ export interface OnboardingDeps {
     report?: typeof onboardingReport;
     startHelper?: () => void;
     loginCodex?: (ctx: Ctx) => Promise<void>;
+    /** Right after the Agents step (0.20.0+): `shard machine setup --from-this-computer --if-needed`, detached. */
+    startMachineSetup?: (ctx: Ctx) => boolean;
 }
 /** Linux's first run orchestrates the same auth, setup and live inspection used by the Mac onboarding. */
 export declare function terminalOnboarding(ctx: Ctx, values: Values, deps?: OnboardingDeps): Promise<number>;

package/dist/terminal-onboarding.js

@@ -6,6 +6,8 @@ import { foundApps, onboardingReport, parseApps } from "./onboarding.js";
 import { requireTermsAcceptance, showLegalNotice } from "./legal.js";
 import { json } from "./format.js";
 import { UsageError } from "./errors.js";
+import { startMachineSetupInBackground } from "./machine-setup.js";
+import { rowText } from "./machine-status.js";
 const handlers = { ...ACCOUNT_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...CODEX_CLOUD_HANDLERS };
 async function loginCodex(ctx) {
     const child = spawn('codex', ['login', ...(!ctx.io.env.DISPLAY && !ctx.io.env.WAYLAND_DISPLAY ? ['--device-auth'] : [])], { env: ctx.io.env, stdio: 'inherit', signal: ctx.signal });
@@ -61,13 +63,21 @@ export async function terminalOnboarding(ctx, values, deps = {}) {
         }
     }
     state = await report(ctx, inspect);
+    // The machine sets itself up from this computer in the background; it never holds the onboarding back.
+    const settingUp = state.ready && (deps.startMachineSetup ?? startMachineSetupInBackground)(ctx);
     if (ctx.json)
         ctx.io.stdout.write(json({ onboarding: state, next: 'shard ./' }));
     else {
         for (const c of state.connections.filter(c => c.id === 'account' || c.picked))
             ctx.io.stdout.write(`${c.id}: ${c.fact}${c.action?.command && c.state !== 'verified' ? ` Run ${c.action.command.join(' ')}.` : ''}\n`);
+        if (settingUp)
+            ctx.io.stdout.write('Your agent is setting up your cloud machine from this computer in the background (shard machine setup --status).\n');
+        // Not set up from here this time (--if-needed found this computer's earlier setup): what the machine is now, so a
+        // failed save is never mistaken for one that carries your tools over.
+        else if (state.machine)
+            ctx.io.stdout.write(`machine: ${rowText(state.machine)}\n`);
         if (state.ready)
-            ctx.io.stdout.write('Ready. Run shard ./ in your project.\n');
+            ctx.io.stdout.write('Agent connections ready. Run shard ./ in your project.\n');
         else
             ctx.io.stdout.write('Finish the connection above, then run shard again.\n');
     }

package/dist/this-computer.d.ts

@@ -0,0 +1,11 @@
+export declare const thisComputer: (platform?: NodeJS.Platform) => string;
+export declare const yourComputer: (platform?: NodeJS.Platform) => string;
+/** The Linux app's default launcher shortcut (apps/desktop-linux/src/main.c), as a GTK accelerator. */
+export declare const LINUX_DEFAULT_SHORTCUT = "<Alt><Shift>space";
+/** A GTK accelerator ("<Control><Shift>space") as the Linux app shows it ("Ctrl+Shift+Space"); shortcutLabel in its core.mjs. */
+export declare function acceleratorLabel(accelerator: string): string;
+/**
+ * The launcher's shortcut as the person presses it: ⌥⇧Space on macOS (the menu bar's), the Linux app's configured one
+ * on Linux, undefined elsewhere.
+ */
+export declare function launcherShortcut(configDir: string, platform?: NodeJS.Platform): string | undefined;

package/dist/this-computer.js

@@ -0,0 +1,36 @@
+/**
+ * How the CLI names the computer it runs on and the launcher's shortcut there (0.20.2+): "this Mac" and ⌥⇧Space on
+ * macOS; "this computer" and the Linux app's configured shortcut (desktop-linux.json, default Alt+Shift+Space) on
+ * Linux. Every line a person reads on Linux comes through here, never a Mac word.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const thisComputer = (platform = process.platform) => (platform === 'darwin' ? 'this Mac' : 'this computer');
+export const yourComputer = (platform = process.platform) => (platform === 'darwin' ? 'your Mac' : 'your computer');
+/** The Linux app's default launcher shortcut (apps/desktop-linux/src/main.c), as a GTK accelerator. */
+export const LINUX_DEFAULT_SHORTCUT = '<Alt><Shift>space';
+/** A GTK accelerator ("<Control><Shift>space") as the Linux app shows it ("Ctrl+Shift+Space"); shortcutLabel in its core.mjs. */
+export function acceleratorLabel(accelerator) {
+    const names = { Control: 'Ctrl', Primary: 'Ctrl', Ctrl: 'Ctrl', Alt: 'Alt', Shift: 'Shift', Super: 'Super', Meta: 'Meta' };
+    const mods = [...accelerator.matchAll(/<(\w+)>/g)].map(m => names[m[1]] ?? m[1]);
+    const key = accelerator.replace(/<\w+>/g, '');
+    return [...mods, key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1)].join('+');
+}
+/**
+ * The launcher's shortcut as the person presses it: ⌥⇧Space on macOS (the menu bar's), the Linux app's configured one
+ * on Linux, undefined elsewhere.
+ */
+export function launcherShortcut(configDir, platform = process.platform) {
+    if (platform === 'darwin')
+        return '⌥⇧Space';
+    if (platform !== 'linux')
+        return undefined;
+    let accelerator = LINUX_DEFAULT_SHORTCUT;
+    try {
+        const prefs = JSON.parse(readFileSync(join(configDir, 'desktop-linux.json'), 'utf8'));
+        if (typeof prefs.shortcut === 'string' && /^(<\w+>)+\S+$/.test(prefs.shortcut))
+            accelerator = prefs.shortcut;
+    }
+    catch { /* the app's default */ }
+    return acceleratorLabel(accelerator);
+}