@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/terminal/inject.js

@@ -0,0 +1,247 @@
+/**
+ * Terminal injection — Gap 2 of the Terminal Engine.
+ *
+ * Where the rest of the engine OPENS a surface (a tab / split running a
+ * command), injection types into an ALREADY-running surface. It's the primitive
+ * a native watchdog (RUSH-1415) needs to nudge a stalled agent with "continue"
+ * delivered into the exact terminal that agent lives in — the gap flagged in
+ * src/lib/session/provenance.ts:20:
+ *
+ *   > Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ *
+ * It mirrors the engine's shape exactly: pure per-backend spec builders (like
+ * `tmuxTabArgv` / `itermTabScript`) produce a `LaunchSpec` (argv), and the same
+ * `runSpec` transport runs it — so injection inherits the engine's local/remote
+ * (`--host` over SSH) execution for free. A `LaunchSpec` never opens anything;
+ * building one is side-effect-free and unit-testable without a display.
+ *
+ * Backends (each addresses the EXACT split, not the frontmost surface):
+ *   - tmux  → `tmux send-keys -t <pane>` — the send-keys primitive addressed by
+ *             pane id + socket (the exact rail provenance.ts identifies).
+ *   - iterm (macOS) → AppleScript `tell session id "<uuid>" to write text` —
+ *             addresses the precise iTerm2 split by its session UUID WITHOUT
+ *             `activate`, so it never steals focus or types into the wrong split.
+ *             Uses the engine's `appleScriptStr` escaper; guarded by the iterm
+ *             backend's `isAvailable` (platform + app installed).
+ *   - vscodium (VSCodium / Cursor / VS Code) → the editor CLI's `--open-url`
+ *             into the swarmify `swarm-ext` extension's `/inject` verb, targeting
+ *             a live-terminals.json terminal by id. Focus-independent, exact
+ *             terminal, and (like the launch backend, src/lib/terminal/backends/
+ *             vscodium-agent.ts) works over `--host` SSH and on Linux.
+ *   - ghostty (macOS) → COARSE only: Ghostty has no scripting dictionary, so
+ *             there is no per-split addressing — this raises a window and types
+ *             via System Events keystrokes, stealing focus. The resolver refuses
+ *             to route here by default (see resolve.ts); it stays behind an
+ *             explicit opt-in.
+ *   - pty   → the `agents pty write` sidecar path (ptyRequest). Local-only —
+ *             the sidecar is not an engine transport surface.
+ *
+ * Ink-TUI Enter semantics: Claude's Ink TUI swallows an Enter fused to the text,
+ * so the default path delivers the text and the Enter as TWO SEPARATE writes
+ * (swarmify's `sendText(text,false)` then `sendText('\r',false)`). `combined`
+ * opts into one fused write for plain shells / REPLs.
+ */
+import { ptyRequest } from '../pty-client.js';
+import { appleScriptStr } from './quote.js';
+import { runSpec } from './transport.js';
+import { itermBackend, ghosttyBackend } from './backends/index.js';
+import { currentContext } from './types.js';
+/** Carriage return — what Enter delivers into a raw PTY/tmux byte stream. */
+const CR = '\r';
+// --- tmux -------------------------------------------------------------------
+/**
+ * argv for `tmux send-keys` targeting a pane by id. Starts with `tmux` (like the
+ * engine's `tmuxTabArgv`) so the same transport runs it locally or over SSH. The
+ * socket, when set, is positioned before the subcommand (`-S` must lead). `-l`
+ * sends the keys literally; without it tmux interprets a key name like `Enter`.
+ *
+ * NOTE: distinct from `sendKeys()` in src/lib/tmux/session.ts — that one
+ * addresses by session *name* on the default socket (the `agents tmux` surface)
+ * and shells out directly; this one addresses by *pane id* + arbitrary socket and
+ * returns an SSH-capable `LaunchSpec` for the engine transport. Don't collapse them.
+ */
+export function tmuxSendKeysArgv(pane, keys, opts = {}) {
+    const argv = ['tmux'];
+    if (opts.socket)
+        argv.push('-S', opts.socket);
+    argv.push('send-keys', '-t', pane);
+    if (opts.literal)
+        argv.push('-l');
+    argv.push(keys);
+    return argv;
+}
+/** The one-or-two send-keys specs for a tmux injection (Ink-safe split by default). */
+export function tmuxInjectSpecs(target, text, o) {
+    const socket = o.socket ?? target.socket;
+    if (o.enter && o.combined) {
+        return [{ argv: tmuxSendKeysArgv(target.pane, text + CR, { literal: true, socket }) }];
+    }
+    const specs = [{ argv: tmuxSendKeysArgv(target.pane, text, { literal: true, socket }) }];
+    // A separate Enter keypress — its own write, so the Ink TUI sees Enter alone.
+    if (o.enter)
+        specs.push({ argv: tmuxSendKeysArgv(target.pane, 'Enter', { socket }) });
+    return specs;
+}
+// --- macOS (iterm / ghostty) ------------------------------------------------
+/**
+ * AppleScript that types into a SPECIFIC iTerm2 split via `tell session id
+ * "<uuid>" to write text` — the exact split provenance's iterm rail identifies,
+ * addressed by its session UUID. Crucially there is NO `activate`: `write text`
+ * delivers to that session directly, so injection never brings iTerm forward or
+ * types into whatever split happens to be focused. Omitting `session` targets
+ * the current session (a direct-call convenience; the resolver always supplies
+ * one).
+ *
+ * Enter semantics — iTerm's `write text` appends a trailing newline, which fuses
+ * text+Enter into ONE write and Claude's Ink TUI swallows it. So the Ink-safe
+ * default (enter, not combined) suppresses that newline (`write text … newline
+ * no`) and sends the Return as a SEPARATE `write text` of a lone CR (`character
+ * id 13`) — two distinct pty writes, Enter seen on its own. `combined` opts into
+ * the single fused `write text` (auto-newline) for plain shells / REPLs.
+ *
+ * NOTE (macOS-only verification pending): the two-write CR path is the safe
+ * choice because it mirrors the tmux/pty Ink-safe split that IS verified here on
+ * Linux; whether a single `write text T` would also submit under Ink can only be
+ * confirmed on a Mac running iTerm (see the PR body).
+ */
+export function itermInjectScript(text, opts) {
+    // Two writes for the Ink-safe default; one fused write for combined / enter=false.
+    const body = opts.enter && opts.combined
+        ? [`write text ${appleScriptStr(text)}`]
+        : opts.enter
+            ? [`write text ${appleScriptStr(text)} newline no`, 'write text (character id 13) newline no']
+            : [`write text ${appleScriptStr(text)} newline no`];
+    const target = opts.session
+        ? `session id ${appleScriptStr(opts.session)}`
+        : 'current session of current window';
+    return [
+        'tell application "iTerm2"',
+        `  tell ${target}`,
+        ...body.map((l) => `    ${l}`),
+        '  end tell',
+        'end tell',
+    ].join('\n');
+}
+/**
+ * AppleScript for Ghostty (no scripting dictionary): raise the target window via
+ * System Events, then keystroke the text and a separate Return. `window` matches
+ * a window whose title contains the string; omitted → the frontmost Ghostty window.
+ */
+export function ghosttyInjectScript(text, opts) {
+    const lines = ['tell application "System Events"', '  tell process "ghostty"', '    set frontmost to true'];
+    if (opts.window) {
+        lines.push(`    perform action "AXRaise" of (first window whose title contains ${appleScriptStr(opts.window)})`);
+    }
+    lines.push('  end tell');
+    lines.push(`  keystroke ${appleScriptStr(text)}`);
+    if (opts.enter)
+        lines.push('  key code 36');
+    lines.push('end tell');
+    return lines.join('\n');
+}
+/** The osascript spec for a macOS injection. One invocation delivers the text + Return. */
+export function appleScriptInjectSpec(target, text, enter, combined = false) {
+    const script = target.backend === 'iterm'
+        ? itermInjectScript(text, { session: target.session, enter, combined })
+        : ghosttyInjectScript(text, { window: target.window, enter });
+    return { argv: ['osascript', '-e', script] };
+}
+// --- vscodium (VSCodium / Cursor / VS Code integrated terminal) -------------
+/** The swarmify extension identifier that owns the swarm-ext URI verbs (matches the launch backend). */
+const EXTENSION_AUTHORITY = 'swarmify.swarm-ext';
+/**
+ * The `<scheme>://swarmify.swarm-ext/inject?p=<payload>` URL the extension
+ * handles to type into an ALREADY-open integrated terminal (the inject sibling
+ * of the launch backend's `/spawn`, src/lib/terminal/backends/vscodium-agent.ts).
+ *
+ * Payload is base64url-encoded JSON in a single `p` param — identical encoding
+ * to `spawnUri`, and for the same reason: VS Code percent-decodes `uri.query`
+ * once before the extension parses it, so a naive multi-param query would
+ * mis-split a text containing `&`/`=`; base64url (`[A-Za-z0-9_-]`) survives that
+ * decode untouched. `terminalId` is the id the extension keys live-terminals.json
+ * on (the session UUID); `enter` tells the extension to submit; `combined` asks
+ * it to fuse text+Enter into one write (default is the Ink-safe two-write split,
+ * mirroring the tmux/iterm paths — the extension owns that split on its side).
+ *
+ * DEPENDENCY: the `/inject` verb ships in the swarm-ext extension via PR #608's
+ * successor (PR #608 introduces `/spawn`; the inject verb + `write`/`enter`
+ * handling is its follow-up). Until that lands, this routes correctly on the CLI
+ * side but the extension will no-op the unknown verb. See the PR body.
+ */
+export function vscodiumInjectUri(scheme, terminalId, text, opts) {
+    const payload = { terminalId, text, enter: opts.enter, combined: opts.combined };
+    const p = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+    return `${scheme}://${EXTENSION_AUTHORITY}/inject?p=${p}`;
+}
+/** The editor-CLI spec for a VSCodium/Cursor/VS Code injection (one `--open-url` invocation). */
+export function vscodiumInjectSpec(target, text, opts) {
+    return { argv: [target.cli, '--open-url', vscodiumInjectUri(target.scheme, target.terminalId, text, opts)] };
+}
+// --- pty --------------------------------------------------------------------
+async function injectPty(target, text, o) {
+    if (o.host && o.host !== 'local') {
+        return { ok: false, backend: 'pty', writes: 0, error: 'pty injection is local-only (the sidecar is not a remote surface)' };
+    }
+    // Same Ink-safe split as tmux: text write, then a separate CR write.
+    const writes = o.enter && o.combined ? [text + CR] : o.enter ? [text, CR] : [text];
+    if (o.dryRun)
+        return { ok: true, backend: 'pty', writes: writes.length };
+    try {
+        for (const input of writes) {
+            const res = await ptyRequest('write', target.id, { input });
+            if (!res.ok)
+                return { ok: false, backend: 'pty', writes: 0, error: res.error ?? 'pty write failed' };
+        }
+        return { ok: true, backend: 'pty', writes: writes.length };
+    }
+    catch (err) {
+        return { ok: false, backend: 'pty', writes: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// --- public entry -----------------------------------------------------------
+/**
+ * Deliver `text` (+ Enter) into an existing terminal surface. Resolves the
+ * target's backend and routes to the matching primitive. Never throws — launch
+ * failures come back in the result, like the engine's `openSurface`.
+ */
+export async function injectIntoTerminal(target, text, opts = {}) {
+    const enter = opts.enter !== false;
+    const combined = opts.combined === true;
+    if (target.backend === 'pty') {
+        return injectPty(target, text, { enter, combined, host: opts.host, dryRun: opts.dryRun });
+    }
+    // tmux + AppleScript + editor-CLI backends all run through the engine transport.
+    const specs = target.backend === 'tmux'
+        ? tmuxInjectSpecs(target, text, { enter, combined, socket: opts.socket })
+        : target.backend === 'vscodium'
+            ? [vscodiumInjectSpec(target, text, { enter, combined })]
+            : [appleScriptInjectSpec(target, text, enter, combined)];
+    // Discrete writes delivered on the far side. tmux counts its send-keys calls.
+    // iterm/vscodium honor `combined` (text+Enter fused into one write). ghostty's
+    // coarse keystroke path ignores `combined` (it always emits keystroke + a
+    // separate Return), so its count tracks `enter` alone.
+    const writes = target.backend === 'tmux'
+        ? specs.length
+        : target.backend === 'ghostty'
+            ? enter ? 2 : 1
+            : enter && !combined ? 2 : 1;
+    if (opts.dryRun)
+        return { ok: true, backend: target.backend, writes, specs };
+    // AppleScript backends: guard on the backend's own availability, but only for a
+    // LOCAL run (a remote host is assumed to have the app — its ssh leg reports failure).
+    if (target.backend === 'iterm' || target.backend === 'ghostty') {
+        if (!opts.host || opts.host === 'local') {
+            const backend = target.backend === 'iterm' ? itermBackend : ghosttyBackend;
+            const ctx = opts.ctx ?? currentContext();
+            if (!backend.isAvailable(ctx)) {
+                return { ok: false, backend: target.backend, writes: 0, specs, error: `${backend.label} is not available here (platform ${ctx.platform})` };
+            }
+        }
+    }
+    for (const spec of specs) {
+        const res = await runSpec(spec, opts.host, opts.resolveHost);
+        if (!res.ok)
+            return { ok: false, backend: target.backend, writes: 0, specs, error: res.error };
+    }
+    return { ok: true, backend: target.backend, writes, specs };
+}

package/dist/lib/terminal/policy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Layout policy — how a batch of surfaces is arranged.
+ *
+ * `two-per-tab` (default) packs sessions two-up: session 1 opens a new tab,
+ * session 2 splits it (right), session 3 opens a new tab, and so on — so each
+ * tab holds a left+right pair. `tabs` gives every session its own tab.
+ */
+import type { Layout } from './types.js';
+export type Packing = 'two-per-tab' | 'tabs';
+/** Assign a layout to each index in a batch of `count` surfaces. */
+export declare function planLayouts(count: number, packing?: Packing): Layout[];

package/dist/lib/terminal/policy.js

@@ -0,0 +1,11 @@
+/** Assign a layout to each index in a batch of `count` surfaces. */
+export function planLayouts(count, packing = 'two-per-tab') {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        if (packing === 'tabs')
+            out.push('tab');
+        else
+            out.push(i % 2 === 0 ? 'tab' : 'split-right');
+    }
+    return out;
+}

package/dist/lib/terminal/quote.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Quoting helpers for building launch commands.
+ *
+ * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
+ * SSH transport so the local and remote legs quote identically. `appleScriptStr`
+ * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
+ */
+import { shellQuote } from '../ssh-exec.js';
+export { shellQuote };
+/** AppleScript double-quoted string literal (escape backslash, then quote). */
+export declare function appleScriptStr(s: string): string;

package/dist/lib/terminal/quote.js

@@ -0,0 +1,13 @@
+/**
+ * Quoting helpers for building launch commands.
+ *
+ * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
+ * SSH transport so the local and remote legs quote identically. `appleScriptStr`
+ * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
+ */
+import { shellQuote } from '../ssh-exec.js';
+export { shellQuote };
+/** AppleScript double-quoted string literal (escape backslash, then quote). */
+export function appleScriptStr(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

package/dist/lib/terminal/resolve.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Inject-target resolution — the safety choke point (RUSH-1415).
+ *
+ * The watchdog knows a session has stalled and wants to nudge it with "continue".
+ * `injectIntoTerminal` (inject.ts) can DELIVER into a target; this module decides
+ * the RIGHT target for a given sessionId — the exact split the agent lives in —
+ * and NEVER guesses. If it can't name a precise rail it returns `addressable:
+ * false` with a reason, and the watchdog skips rather than typing into the
+ * frontmost / wrong split.
+ *
+ * Resolution reads the agent's INHERITED ENV (via session provenance) plus the
+ * IDE's live-terminals registry (off disk) — no cooperation from the agent:
+ *
+ *   tmux  > iterm > vscodium > pty
+ *
+ * tmux wins whenever present: a `tmux send-keys -t <pane>` reaches the pane no
+ * matter which host app (iTerm / Ghostty / VS Code) is above it, so it's correct
+ * inside ANY of them. Absent tmux, the host-app rail: iTerm2's exact split by
+ * session UUID (env), or a VSCodium/Cursor/VS Code integrated terminal addressed
+ * by its live-terminals id. Ghostty has no per-split addressing (no scripting
+ * dictionary), so a Ghostty-hosted session with no tmux is honestly reported
+ * un-addressable — the coarse focus-stealing window path stays behind an explicit
+ * opt-in and is never chosen by default.
+ */
+import type { ActiveSession } from '../session/active.js';
+import type { InjectTarget } from './inject.js';
+/** A resolved rail, or an honest refusal. The watchdog acts only on `addressable: true`. */
+export type InjectRail = 'tmux' | 'iterm' | 'vscodium' | 'ghostty' | 'pty';
+export type InjectResolution = {
+    addressable: true;
+    rail: InjectRail;
+    target: InjectTarget;
+    note?: string;
+} | {
+    addressable: false;
+    reason: string;
+};
+export interface ResolveOptions {
+    /**
+     * Allow the COARSE Ghostty path (raise the frontmost/opt-in window and type via
+     * System Events keystrokes — steals focus, not split-precise). Off by default:
+     * a Ghostty session with no tmux resolves to un-addressable instead.
+     */
+    allowGhosttyFocus?: boolean;
+    /**
+     * A known `agents pty` sidecar id for this session, if the caller has one. No
+     * automatic sessionId -> pty mapping exists yet, so pty is only emitted when
+     * supplied here (the lowest-precedence rail).
+     */
+    ptyId?: string;
+}
+/**
+ * Resolve a target from an already-fetched ActiveSession. Pure — no I/O — so the
+ * precedence logic is unit-testable without the process table. This is where the
+ * tmux > iterm > vscodium > pty precedence and the Ghostty refusal live.
+ */
+export declare function resolveInjectTargetForSession(session: ActiveSession, opts?: ResolveOptions): InjectResolution;
+/**
+ * The single resolver the watchdog calls: sessionId -> a precise InjectTarget or
+ * an honest refusal. Fetches the active session (which carries provenance, host,
+ * and pid), then applies the pure precedence above. Returns `addressable: false`
+ * when the session isn't live / can't be found — never a guess.
+ */
+export declare function resolveInjectTarget(sessionId: string, opts?: ResolveOptions): Promise<InjectResolution>;

package/dist/lib/terminal/resolve.js

@@ -0,0 +1,90 @@
+import { getActiveSessions } from '../session/active.js';
+/** The editor CLIs that speak the swarm-ext URI protocol, keyed by the host detectHost() reports. */
+const IDE_INJECT_VARIANTS = {
+    codium: { cli: 'codium', scheme: 'vscodium' },
+    cursor: { cli: 'cursor', scheme: 'cursor' },
+    code: { cli: 'code', scheme: 'vscode' },
+};
+/**
+ * Resolve a target from an already-fetched ActiveSession. Pure — no I/O — so the
+ * precedence logic is unit-testable without the process table. This is where the
+ * tmux > iterm > vscodium > pty precedence and the Ghostty refusal live.
+ */
+export function resolveInjectTargetForSession(session, opts = {}) {
+    const prov = session.provenance;
+    // 1. tmux — correct inside any host app, so it takes precedence whenever the
+    //    env carries a pane. (provenance.reply already encodes tmux-over-iterm.)
+    if (prov?.mux?.kind === 'tmux' && prov.mux.pane) {
+        return {
+            addressable: true,
+            rail: 'tmux',
+            target: { backend: 'tmux', pane: prov.mux.pane, socket: prov.mux.socket },
+        };
+    }
+    // 2. iterm — the exact split by session UUID (env-derived, focus-safe).
+    if (prov?.reply?.rail === 'iterm') {
+        return {
+            addressable: true,
+            rail: 'iterm',
+            target: { backend: 'iterm', session: prov.reply.session },
+        };
+    }
+    // 3. vscodium — a VSCodium/Cursor/VS Code integrated terminal, addressed by the
+    //    id the extension keys live-terminals.json on (the session UUID). Only when
+    //    the session is IDE-hosted AND we know its id.
+    const variant = session.host ? IDE_INJECT_VARIANTS[session.host] : undefined;
+    if (variant) {
+        if (!session.sessionId) {
+            return { addressable: false, reason: `IDE terminal (${session.host}) has no session id to address` };
+        }
+        return {
+            addressable: true,
+            rail: 'vscodium',
+            target: { backend: 'vscodium', terminalId: session.sessionId, cli: variant.cli, scheme: variant.scheme },
+        };
+    }
+    // 4. pty — lowest precedence, only when the caller supplied a sidecar id.
+    if (opts.ptyId) {
+        return { addressable: true, rail: 'pty', target: { backend: 'pty', id: opts.ptyId } };
+    }
+    // 5. Ghostty — no per-split addressing exists. Refuse by default; the coarse,
+    //    focus-stealing window path is opt-in only.
+    if (session.host === 'ghostty') {
+        if (opts.allowGhosttyFocus) {
+            return {
+                addressable: true,
+                rail: 'ghostty',
+                target: { backend: 'ghostty' },
+                note: 'coarse Ghostty window path (opt-in): raises a window and types into the FOCUSED split — not split-precise',
+            };
+        }
+        return { addressable: false, reason: 'un-addressable (ghostty, no tmux): no per-split addressing; watchdog skips' };
+    }
+    return {
+        addressable: false,
+        reason: session.host
+            ? `no precise inject rail for host '${session.host}' (no tmux/iterm/IDE terminal detected)`
+            : 'no inject rail: session is not inside tmux, iTerm, or an IDE terminal',
+    };
+}
+/**
+ * The single resolver the watchdog calls: sessionId -> a precise InjectTarget or
+ * an honest refusal. Fetches the active session (which carries provenance, host,
+ * and pid), then applies the pure precedence above. Returns `addressable: false`
+ * when the session isn't live / can't be found — never a guess.
+ */
+export async function resolveInjectTarget(sessionId, opts = {}) {
+    if (!sessionId)
+        return { addressable: false, reason: 'no sessionId given' };
+    let sessions;
+    try {
+        sessions = await getActiveSessions();
+    }
+    catch (err) {
+        return { addressable: false, reason: `could not list active sessions: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const session = sessions.find((s) => s.sessionId === sessionId);
+    if (!session)
+        return { addressable: false, reason: `no live session found for id ${sessionId}` };
+    return resolveInjectTargetForSession(session, opts);
+}

package/dist/lib/terminal/shell.d.ts

@@ -0,0 +1,6 @@
+/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
+export declare function loginExec(cwd: string, command: string[]): string;
+/** `exec <command>` — for backends that set the working directory natively. */
+export declare function execOnly(command: string[]): string;
+/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
+export declare function iLoginShell(inner: string): string;

package/dist/lib/terminal/shell.js

@@ -0,0 +1,23 @@
+/**
+ * Interactive-login-shell wrappers shared by every backend.
+ *
+ * `-i` is load-bearing, not cosmetic: the version-pinned shims (e.g.
+ * `claude@2.1.187`) live in `~/.agents/.cache/shims`, which `.zshrc` puts on
+ * PATH for *interactive* shells only. A plain `zsh -lc` (login, non-interactive)
+ * skips `.zshrc`, so the shim isn't found and the surface dies with "command not
+ * found". Every backend wraps its command in `zsh -ilc` for this reason — do not
+ * drop the `-i`.
+ */
+import { shellQuote } from './quote.js';
+/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
+export function loginExec(cwd, command) {
+    return `cd ${shellQuote(cwd)} && exec ${command.join(' ')}`;
+}
+/** `exec <command>` — for backends that set the working directory natively. */
+export function execOnly(command) {
+    return `exec ${command.join(' ')}`;
+}
+/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
+export function iLoginShell(inner) {
+    return `zsh -ilc ${shellQuote(inner)}`;
+}

package/dist/lib/terminal/transport.d.ts

@@ -0,0 +1,15 @@
+import type { LaunchSpec } from './types.js';
+/** Resolve a host alias to an ssh target. Default: identity (ssh_config resolves it). */
+export type HostResolver = (alias: string) => string;
+export interface RunResult {
+    ok: boolean;
+    error?: string;
+}
+/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
+export declare function runLocal(spec: LaunchSpec): Promise<RunResult>;
+/** Serialize a launch argv into a single POSIX-quoted shell command string. */
+export declare function remoteCommand(spec: LaunchSpec): string;
+/** Run the spec on a remote host over SSH. */
+export declare function runRemote(spec: LaunchSpec, target: string): RunResult;
+/** Run a spec locally (no host / 'local') or on a resolved remote host. */
+export declare function runSpec(spec: LaunchSpec, host?: string, resolveHost?: HostResolver): Promise<RunResult>;

package/dist/lib/terminal/transport.js

@@ -0,0 +1,40 @@
+/**
+ * Transport — runs a LaunchSpec locally or on a remote host.
+ *
+ * Local: spawn the launcher (osascript / tmux) and wait for it to exit — these
+ * are short-lived commands that create the surface and return, so waiting gives
+ * a real success/failure. Remote: serialize the argv into one shell string and
+ * hand it to `sshExec` — the same hardened SSH primitive `agents sessions
+ * --host` and the browser driver use (target-injection guard, POSIX quoting,
+ * connection multiplexing).
+ */
+import { spawn } from 'child_process';
+import { sshExec } from '../ssh-exec.js';
+import { shellQuote } from './quote.js';
+/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
+export function runLocal(spec) {
+    return new Promise((resolve) => {
+        const child = spawn(spec.argv[0], spec.argv.slice(1), { stdio: 'ignore' });
+        child.on('error', (err) => resolve({ ok: false, error: err.message }));
+        child.on('close', (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: `${spec.argv[0]} exited with code ${code}` }));
+    });
+}
+/** Serialize a launch argv into a single POSIX-quoted shell command string. */
+export function remoteCommand(spec) {
+    return spec.argv.map(shellQuote).join(' ');
+}
+/** Run the spec on a remote host over SSH. */
+export function runRemote(spec, target) {
+    const res = sshExec(target, remoteCommand(spec), { multiplex: true });
+    if (res.code === 0)
+        return { ok: true };
+    const err = (res.stderr || '').trim();
+    return { ok: false, error: err || `ssh exited with code ${res.code}` };
+}
+/** Run a spec locally (no host / 'local') or on a resolved remote host. */
+export async function runSpec(spec, host, resolveHost) {
+    if (!host || host === 'local')
+        return runLocal(spec);
+    const target = resolveHost ? resolveHost(host) : host;
+    return runRemote(spec, target);
+}

package/dist/lib/terminal/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Core types for the terminal launch engine.
+ *
+ * The engine opens an *interactive* surface — a tab or a split pane — running a
+ * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
+ * machine or a remote host. This is distinct from cloud providers
+ * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
+ * is attended and live. See docs/terminal-engine.md.
+ */
+/** An interactive terminal backend the engine can drive. */
+export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent';
+/** Which way a split pane grows. `right` = side-by-side; `down` = stacked. */
+export type SplitDirection = 'right' | 'down';
+/** Where a surface lands: a new tab, or a split of the current pane. */
+export type Layout = 'tab' | 'split-right' | 'split-down';
+/** Ambient facts a backend needs to decide availability and detection. */
+export interface EngineContext {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}
+/** Snapshot the live process context. */
+export declare function currentContext(): EngineContext;
+/** The concrete OS command that opens a surface — the pure output of a backend. */
+export interface LaunchSpec {
+    /** argv to run (e.g. `['osascript','-e',script]` or `['tmux','split-window',…]`). */
+    argv: string[];
+}
+/** A single "open this command as this surface" instruction. */
+export interface LaunchRequest {
+    backend: Backend;
+    layout: Layout;
+    /** Working directory the command runs in. */
+    cwd: string;
+    /** argv to exec in the surface (e.g. a resume command). */
+    command: string[];
+    /** undefined / 'local' = this machine; otherwise a resolvable host alias. */
+    host?: string;
+}
+/** Outcome of opening one surface. Never throws for launch failures — reports them. */
+export interface LaunchResult {
+    ok: boolean;
+    request: LaunchRequest;
+    error?: string;
+}
+/**
+ * A terminal backend: pure builders + an availability check. No side effects —
+ * building a spec never opens anything, so every backend is unit-testable
+ * without a display. The engine's transport is what actually runs the spec.
+ */
+export interface TerminalBackend {
+    readonly id: Backend;
+    readonly label: string;
+    /** Can this backend be driven here? (platform + app installed / inside tmux). */
+    isAvailable(ctx: EngineContext): boolean;
+    /** Command that opens a new tab running `command` in `cwd`. */
+    buildTab(cwd: string, command: string[]): LaunchSpec;
+    /** Command that splits the current surface, running `command` in `cwd`. */
+    buildSplit(cwd: string, command: string[], direction: SplitDirection): LaunchSpec;
+}

package/dist/lib/terminal/types.js

@@ -0,0 +1,13 @@
+/**
+ * Core types for the terminal launch engine.
+ *
+ * The engine opens an *interactive* surface — a tab or a split pane — running a
+ * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
+ * machine or a remote host. This is distinct from cloud providers
+ * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
+ * is attended and live. See docs/terminal-engine.md.
+ */
+/** Snapshot the live process context. */
+export function currentContext() {
+    return { platform: process.platform, env: process.env };
+}