@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/dist/lib/ssh-tunnel.js

@@ -22,7 +22,6 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { randomBytes } from 'crypto';
-import { Transform } from 'stream';
 import { sshExec, SSH_OPTS } from './ssh-exec.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
@@ -30,19 +29,18 @@ import { sshTargetFor } from './devices/connect.js';
 import { hostNameFor } from './devices/ssh-config.js';
 import { getCacheDir } from './state.js';
 import { openComputerClient, resolveTcpEndpoint } from './computer-rpc.js';
-/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure. */
+/** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
+ *
+ * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
+ * so the tunnel inherits the same options — crucially the keepalive, which lets
+ * a dropped `-N` tunnel exit instead of lingering as a zombie on the laptop. */
 export function buildTunnelArgs(user, host, localPort, remotePort) {
     return [
         '-L',
         `${localPort}:127.0.0.1:${remotePort}`,
         `${user}@${host}`,
         '-N',
-        '-o',
-        'StrictHostKeyChecking=accept-new',
-        '-o',
-        'BatchMode=yes',
-        '-o',
-        'ConnectTimeout=10',
+        ...SSH_OPTS,
     ];
 }
 /**
@@ -150,10 +148,15 @@ export async function resolveRemoteDevice(name) {
     return { device, target, user, host };
 }
 /**
- * PowerShell that streams base64 from stdin, decodes it incrementally to
- * %LOCALAPPDATA%\agents\computer-helper-win.exe, and stops any running instance
- * first so the file isn't locked. The CryptoStream/FromBase64Transform decode
- * is streaming — the ~156MB exe never lands in memory whole on the remote.
+ * Single-quote a string for embedding inside a PowerShell literal.
+ */
+function psSingleQuote(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/**
+ * PowerShell that resolves the destination under %LOCALAPPDATA%\agents and
+ * stops any running instance first so the file is not locked. The caller copies
+ * the exe with scp and then verifies the byte count separately.
  */
 export function buildPushScript() {
     return [
@@ -161,15 +164,18 @@ export function buildPushScript() {
         `New-Item -ItemType Directory -Force -Path $dir | Out-Null`,
         `$dst = Join-Path $dir '${WIN_HELPER_EXE}'`,
         `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
-        `$si = [Console]::OpenStandardInput()`,
-        `$t = New-Object Security.Cryptography.FromBase64Transform`,
-        `$cs = New-Object Security.Cryptography.CryptoStream($si, $t, [Security.Cryptography.CryptoStreamMode]::Read)`,
-        `$fs = [IO.File]::Create($dst)`,
-        `$cs.CopyTo($fs)`,
-        `$fs.Close(); $cs.Close()`,
         `Write-Output $dst`,
     ].join('; ');
 }
+/** PowerShell that verifies scp wrote the expected number of bytes. */
+export function buildVerifyPushScript(remotePath, expectedBytes) {
+    return [
+        `$dst = ${psSingleQuote(remotePath)}`,
+        `$item = Get-Item -LiteralPath $dst -ErrorAction Stop`,
+        `if ($item.Length -ne ${expectedBytes}) { throw "helper copy length mismatch: expected ${expectedBytes}, got $($item.Length)" }`,
+        `Write-Output "$dst $($item.Length)"`,
+    ].join('; ');
+}
 /**
  * PowerShell that registers the daemon as a LOGON scheduled task. Interactive
  * logon type + Highest run level so the daemon runs in the real desktop session
@@ -195,51 +201,32 @@ export function buildUnregisterTaskScript(taskName) {
         `Get-Process -Name 'computer-helper-win' -ErrorAction SilentlyContinue | Stop-Process -Force -ErrorAction SilentlyContinue`,
     ].join('; ');
 }
+/** Convert a Windows path returned by PowerShell into the scp/SFTP path form. */
+export function scpRemotePath(remotePath) {
+    return remotePath.replace(/\\/g, '/');
+}
 /**
- * `setup --host`: push the exe, then register + start the LOGON task. Both hops
- * go through `sshExec` (BatchMode key auth — the same hardening the browser
- * driver and `agents ssh` use). Throws with the remote stderr on any failure.
- */
-/**
- * Base64-encode a byte stream in 3-byte-aligned chunks so the concatenated
- * output is valid (every chunk boundary lands on a base64 quantum).
+ * Build the scp argv used for the helper exe transfer. Exported so tests can
+ * assert the real binary copy path keeps BatchMode and does not route bytes
+ * through a PowerShell decoder.
  */
-class Base64Encode extends Transform {
-    leftover = Buffer.alloc(0);
-    _transform(chunk, _enc, cb) {
-        const buf = this.leftover.length ? Buffer.concat([this.leftover, chunk]) : chunk;
-        const usable = buf.length - (buf.length % 3);
-        this.leftover = Buffer.from(buf.subarray(usable));
-        if (usable > 0)
-            this.push(buf.subarray(0, usable).toString('base64'));
-        cb();
-    }
-    _flush(cb) {
-        if (this.leftover.length)
-            this.push(this.leftover.toString('base64'));
-        cb();
-    }
+export function buildScpArgs(target, remotePath, filePath) {
+    return [...SSH_OPTS, filePath, `${target}:${scpRemotePath(remotePath)}`];
 }
 /**
- * Stream a local file to a remote command's stdin over ssh, base64-encoded on
- * the fly. Async spawn + piping honors backpressure; the previous
- * `spawnSync({ input })` blob deadlocked once the ssh socket buffer filled
- * (~4MB) on large files (the 157MB Windows helper reproduced this reliably),
- * and worse, reported a false success leaving a 0-byte remote file. Rejects on
- * any pipe error so a broken transfer fails loudly instead.
+ * Copy a local file to the remote destination with scp. This is a binary
+ * transfer; no base64 transform runs on either side.
  */
-function streamFileOverSsh(target, remoteCmd, filePath, timeoutMs = 600_000) {
+function copyFileOverScp(target, remotePath, filePath, timeoutMs = 600_000) {
     return new Promise((resolve, reject) => {
-        const child = spawn('ssh', [...SSH_OPTS, target, remoteCmd], {
-            stdio: ['pipe', 'pipe', 'pipe'],
+        const child = spawn('scp', buildScpArgs(target, remotePath, filePath), {
+            stdio: ['ignore', 'ignore', 'pipe'],
         });
         let stderr = '';
-        let stdout = '';
         child.stderr.on('data', (d) => (stderr += d.toString()));
-        child.stdout.on('data', (d) => (stdout += d.toString()));
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
-            reject(new Error(`ssh push to ${target} timed out after ${timeoutMs}ms`));
+            reject(new Error(`scp push to ${target} timed out after ${timeoutMs}ms`));
         }, timeoutMs);
         const fail = (e) => {
             clearTimeout(timer);
@@ -247,30 +234,41 @@ function streamFileOverSsh(target, remoteCmd, filePath, timeoutMs = 600_000) {
             reject(e);
         };
         child.on('error', fail);
-        child.stdin.on('error', fail); // EPIPE if the remote decoder dies mid-stream
         child.on('close', (code) => {
             clearTimeout(timer);
-            resolve({ code, stderr: stderr || stdout });
+            resolve({ code, stderr });
         });
-        const src = fs.createReadStream(filePath);
-        src.on('error', fail);
-        // disk -> aligned base64 -> ssh stdin; .pipe() applies backpressure
-        src.pipe(new Base64Encode()).pipe(child.stdin);
     });
 }
+/**
+ * `setup --host`: push the exe, then register + start the LOGON task. Remote
+ * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening
+ * the browser driver and `agents ssh` use), and the large exe rides a binary
+ * scp transfer. Throws with the remote stderr on any failure.
+ */
 export async function setupRemoteHelper(name) {
     const { target } = await resolveRemoteDevice(name);
     const exe = resolveWinHelperExe();
     if (!exe) {
         throw new Error(`Windows helper exe not built. Run: bash scripts/build-win.sh`);
     }
-    // Push: stream the exe from disk, base64-encoded on the fly, to the remote
-    // decoder. Streaming (vs a single spawnSync `input` blob) honors ssh socket
-    // backpressure — the blob path deadlocks once the socket buffer fills (~4MB).
-    const push = await streamFileOverSsh(target, encodePowerShell(buildPushScript()), exe);
+    const prep = sshExec(target, encodePowerShell(buildPushScript()), { timeoutMs: 60_000 });
+    if (prep.code !== 0) {
+        throw new Error(`preparing helper exe path on '${name}' failed (exit ${prep.code ?? 'null'}): ${prep.stderr.trim() || prep.stdout.trim()}`);
+    }
+    const remotePath = prep.stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    if (!remotePath) {
+        throw new Error(`preparing helper exe path on '${name}' did not return a destination path`);
+    }
+    const push = await copyFileOverScp(target, remotePath, exe);
     if (push.code !== 0) {
         throw new Error(`pushing helper exe to '${name}' failed (exit ${push.code ?? 'null'}): ${push.stderr.trim()}`);
     }
+    const expectedBytes = fs.statSync(exe).size;
+    const verify = sshExec(target, encodePowerShell(buildVerifyPushScript(remotePath, expectedBytes)), { timeoutMs: 60_000 });
+    if (verify.code !== 0) {
+        throw new Error(`verifying helper exe on '${name}' failed (exit ${verify.code ?? 'null'}): ${verify.stderr.trim() || verify.stdout.trim()}`);
+    }
     // Register + start the LOGON task.
     const reg = sshExec(target, encodePowerShell(buildRegisterTaskScript(REMOTE_HELPER_PORT, REMOTE_TASK_NAME)), {
         timeoutMs: 60_000,

package/dist/lib/staleness/writers/hooks.js

@@ -32,7 +32,7 @@ function buildHooksWriter(agent) {
             }
             // Native hook registration in settings.json/hooks.json. Grok auto-
             // discovers from ~/.grok/hooks/ so the file copy is sufficient.
-            if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity' || agent === 'kimi') {
+            if (agent === 'claude' || agent === 'codex' || agent === 'gemini' || agent === 'antigravity' || agent === 'kimi' || agent === 'droid') {
                 registerHooksToSettings(agent, versionHome);
             }
             return { synced };

package/dist/lib/startup/command-registry.d.ts

@@ -69,6 +69,8 @@ export declare const loadTmux: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
 export declare const loadHosts: ModuleLoader;
+export declare const loadLogs: ModuleLoader;
+export declare const loadEvents: ModuleLoader;
 export declare const loadSsh: ModuleLoader;
 export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;

package/dist/lib/startup/command-registry.js

@@ -47,6 +47,8 @@ export const loadTmux = async () => (await import('../../commands/tmux.js')).reg
 export const loadBrowser = async () => (await import('../../commands/browser.js')).registerBrowserCommand;
 export const loadComputer = async () => (await import('../../commands/computer.js')).registerComputerCommand;
 export const loadHosts = async () => (await import('../../commands/hosts.js')).registerHostsCommand;
+export const loadLogs = async () => (await import('../../commands/logs.js')).registerLogsCommand;
+export const loadEvents = async () => (await import('../../commands/events.js')).registerEventsCommand;
 export const loadSsh = async () => (await import('../../commands/ssh.js')).registerSshCommands;
 export const loadPull = async () => (await import('../../commands/pull.js')).registerPullCommand;
 export const loadPush = async () => (await import('../../commands/push.js')).registerPushCommand;
@@ -131,6 +133,8 @@ export const COMMAND_LOADERS = {
     browser: [loadBrowser],
     computer: [loadComputer],
     hosts: [loadHosts],
+    logs: [loadLogs],
+    events: [loadEvents],
     ssh: [loadSsh],
     devices: [loadSsh],
     pull: [loadPull],

package/dist/lib/teams/registry.js

@@ -13,6 +13,7 @@ import * as path from 'path';
 import { randomBytes } from 'crypto';
 import lockfile from 'proper-lockfile';
 import { getTeamsRegistryPath } from '../state.js';
+import { emit } from '../events.js';
 async function registryPath() {
     return getTeamsRegistryPath();
 }
@@ -98,39 +99,50 @@ export async function createTeam(name, options) {
         throw new Error('Cannot use both --enable-worktrees and --use-worktree. Pick one.');
     }
     const p = await registryPath();
-    return withRegistryLock(p, async () => {
+    const meta = await withRegistryLock(p, async () => {
         const reg = await loadTeams();
         if (reg[name]) {
             throw new Error(`Team '${name}' already exists`);
         }
-        const meta = {
+        const m = {
             created_at: new Date().toISOString(),
             ...(options?.description ? { description: options.description } : {}),
             ...(options?.enableWorktrees ? { enable_worktrees: true } : {}),
             ...(options?.useWorktree ? { use_worktree: options.useWorktree } : {}),
         };
-        reg[name] = meta;
+        reg[name] = m;
         await saveTeams(reg);
-        return meta;
+        return m;
     });
+    // Audit the lifecycle boundary, not the CLI shell — captures every creation
+    // path (create + ensure) with team metadata the generic command log lacks.
+    emit('teams.create', { module: 'teams', team: name, worktrees: Boolean(options?.enableWorktrees || options?.useWorktree) });
+    return meta;
 }
 /** Return existing team metadata or create a new team if it does not exist. */
 export async function ensureTeam(name) {
     const p = await registryPath();
-    return withRegistryLock(p, async () => {
+    let created = false;
+    const meta = await withRegistryLock(p, async () => {
         const reg = await loadTeams();
         if (reg[name])
             return reg[name];
-        const meta = { created_at: new Date().toISOString() };
-        reg[name] = meta;
+        const m = { created_at: new Date().toISOString() };
+        reg[name] = m;
         await saveTeams(reg);
-        return meta;
+        created = true;
+        return m;
     });
+    // `teams add` auto-creates the team on first teammate — audit that creation
+    // too, but only when it actually happened (not the get-existing path).
+    if (created)
+        emit('teams.create', { module: 'teams', team: name, worktrees: false });
+    return meta;
 }
 /** Remove a team from the registry. Returns false if the team did not exist. */
 export async function removeTeam(name) {
     const p = await registryPath();
-    return withRegistryLock(p, async () => {
+    const existed = await withRegistryLock(p, async () => {
         const reg = await loadTeams();
         if (!reg[name])
             return false;
@@ -138,6 +150,10 @@ export async function removeTeam(name) {
         await saveTeams(reg);
         return true;
     });
+    // "Disband" — only fires when a real team was removed, not a no-op.
+    if (existed)
+        emit('teams.disband', { module: 'teams', team: name });
+    return existed;
 }
 /** Check whether a team with the given name exists in the registry. */
 export async function teamExists(name) {

package/dist/lib/terminal/backends/ghostty.d.ts

@@ -0,0 +1,6 @@
+import type { TerminalBackend, SplitDirection } from '../types.js';
+/** AppleScript that opens a Ghostty tab (a window if none is open). */
+export declare function ghosttyTabScript(cwd: string, command: string[]): string;
+/** AppleScript that splits the current Ghostty surface (a window if none is open). */
+export declare function ghosttySplitScript(cwd: string, command: string[], direction: SplitDirection): string;
+export declare const ghosttyBackend: TerminalBackend;

package/dist/lib/terminal/backends/ghostty.js

@@ -0,0 +1,69 @@
+/**
+ * Ghostty backend — drives Ghostty (>= 1.3) via AppleScript (`osascript`).
+ *
+ * Ghostty's `new surface configuration` record carries the working directory and
+ * command natively, so no `cd` wrapper is needed. Tab: `new tab` (or a window
+ * when none is open). Split: `split <surface> direction right|down`, where the
+ * current surface is `focused terminal of selected tab of front window`
+ * (verified against Ghostty 1.3.1 — a surface is a "terminal" in its AS model).
+ */
+import * as fs from 'fs';
+import { appleScriptStr } from '../quote.js';
+import { execOnly, iLoginShell } from '../shell.js';
+const GHOSTTY_APP = '/Applications/Ghostty.app';
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/** Shared prologue: activate + a surface configuration carrying cwd + command. */
+function configPrologue(cwd, command) {
+    const cmd = appleScriptStr(iLoginShell(execOnly(command)));
+    return [
+        'tell application "Ghostty"',
+        '  activate',
+        '  set cfg to new surface configuration',
+        `  set initial working directory of cfg to ${appleScriptStr(cwd)}`,
+        `  set command of cfg to ${cmd}`,
+    ];
+}
+/** AppleScript that opens a Ghostty tab (a window if none is open). */
+export function ghosttyTabScript(cwd, command) {
+    return [
+        ...configPrologue(cwd, command),
+        '  if (count of windows) is 0 then',
+        '    new window with configuration cfg',
+        '  else',
+        '    new tab in front window with configuration cfg',
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+/** AppleScript that splits the current Ghostty surface (a window if none is open). */
+export function ghosttySplitScript(cwd, command, direction) {
+    return [
+        ...configPrologue(cwd, command),
+        '  if (count of windows) is 0 then',
+        '    new window with configuration cfg',
+        '  else',
+        `    split (focused terminal of selected tab of front window) direction ${direction} with configuration cfg`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+export const ghosttyBackend = {
+    id: 'ghostty',
+    label: 'Ghostty',
+    isAvailable(ctx) {
+        return ctx.platform === 'darwin' && appExists(GHOSTTY_APP);
+    },
+    buildTab(cwd, command) {
+        return { argv: ['osascript', '-e', ghosttyTabScript(cwd, command)] };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: ['osascript', '-e', ghosttySplitScript(cwd, command, direction)] };
+    },
+};

package/dist/lib/terminal/backends/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Backend registry + current-terminal detection.
+ */
+import type { Backend, EngineContext, TerminalBackend } from '../types.js';
+import { itermBackend } from './iterm.js';
+import { ghosttyBackend } from './ghostty.js';
+import { tmuxBackend } from './tmux.js';
+/** All known interactive backends, keyed by id. */
+export declare const BACKENDS: Record<Backend, TerminalBackend>;
+/**
+ * The backend for the terminal the CLI is currently running in, or null if we
+ * can't open a surface into it. tmux wins (via `$TMUX`) because a tmux pane can
+ * live inside iTerm/Ghostty; otherwise fall back to `TERM_PROGRAM`.
+ */
+export declare function detectCurrentBackend(ctx: EngineContext): Backend | null;
+/** Backends that can actually be driven in this context. */
+export declare function availableBackends(ctx: EngineContext): TerminalBackend[];
+export { itermBackend, ghosttyBackend, tmuxBackend };

package/dist/lib/terminal/backends/index.js

@@ -0,0 +1,29 @@
+import { itermBackend } from './iterm.js';
+import { ghosttyBackend } from './ghostty.js';
+import { tmuxBackend } from './tmux.js';
+/** All known interactive backends, keyed by id. */
+export const BACKENDS = {
+    iterm: itermBackend,
+    ghostty: ghosttyBackend,
+    tmux: tmuxBackend,
+};
+/**
+ * The backend for the terminal the CLI is currently running in, or null if we
+ * can't open a surface into it. tmux wins (via `$TMUX`) because a tmux pane can
+ * live inside iTerm/Ghostty; otherwise fall back to `TERM_PROGRAM`.
+ */
+export function detectCurrentBackend(ctx) {
+    if (ctx.env.TMUX)
+        return 'tmux';
+    const term = (ctx.env.TERM_PROGRAM || '').toLowerCase();
+    if (term.includes('iterm'))
+        return 'iterm';
+    if (term.includes('ghostty'))
+        return 'ghostty';
+    return null;
+}
+/** Backends that can actually be driven in this context. */
+export function availableBackends(ctx) {
+    return Object.values(BACKENDS).filter((b) => b.isAvailable(ctx));
+}
+export { itermBackend, ghosttyBackend, tmuxBackend };

package/dist/lib/terminal/backends/iterm.d.ts

@@ -0,0 +1,6 @@
+import type { TerminalBackend, SplitDirection } from '../types.js';
+/** AppleScript that opens an iTerm tab (a window if none is open) running the command. */
+export declare function itermTabScript(cwd: string, command: string[]): string;
+/** AppleScript that splits the current iTerm session (a window if none is open). */
+export declare function itermSplitScript(cwd: string, command: string[], direction: SplitDirection): string;
+export declare const itermBackend: TerminalBackend;

package/dist/lib/terminal/backends/iterm.js

@@ -0,0 +1,62 @@
+/**
+ * iTerm backend — drives iTerm2 via AppleScript (`osascript`).
+ *
+ * Tab: creates a tab in the current window (or a window when none is open).
+ * Split: splits the current session — `split vertically` (side-by-side, a
+ * vertical divider) for `right`, `split horizontally` (stacked) for `down`.
+ */
+import * as fs from 'fs';
+import { appleScriptStr } from '../quote.js';
+import { loginExec, iLoginShell } from '../shell.js';
+const ITERM_APP = '/Applications/iTerm.app';
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/** AppleScript that opens an iTerm tab (a window if none is open) running the command. */
+export function itermTabScript(cwd, command) {
+    const cmd = appleScriptStr(iLoginShell(loginExec(cwd, command)));
+    return [
+        'tell application "iTerm2"',
+        '  activate',
+        '  if (count of windows) is 0 then',
+        `    create window with default profile command ${cmd}`,
+        '  else',
+        `    tell current window to create tab with default profile command ${cmd}`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+/** AppleScript that splits the current iTerm session (a window if none is open). */
+export function itermSplitScript(cwd, command, direction) {
+    const cmd = appleScriptStr(iLoginShell(loginExec(cwd, command)));
+    // iTerm: "split vertically" = a vertical divider = panes side by side (right).
+    const verb = direction === 'right' ? 'split vertically' : 'split horizontally';
+    return [
+        'tell application "iTerm2"',
+        '  activate',
+        '  if (count of windows) is 0 then',
+        `    create window with default profile command ${cmd}`,
+        '  else',
+        `    tell current session of current window to ${verb} with default profile command ${cmd}`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+export const itermBackend = {
+    id: 'iterm',
+    label: 'iTerm',
+    isAvailable(ctx) {
+        return ctx.platform === 'darwin' && appExists(ITERM_APP);
+    },
+    buildTab(cwd, command) {
+        return { argv: ['osascript', '-e', itermTabScript(cwd, command)] };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: ['osascript', '-e', itermSplitScript(cwd, command, direction)] };
+    },
+};

package/dist/lib/terminal/backends/tmux.d.ts

@@ -0,0 +1,14 @@
+/**
+ * tmux backend — opens windows and splits in the running tmux server.
+ *
+ * cwd is passed natively via `-c`, so the command is wrapped in `zsh -ilc` with
+ * no `cd`. `split-window -h` = side-by-side (right); `-v` = stacked (down).
+ * Available only when the CLI is running inside tmux (`$TMUX` set) — otherwise
+ * there is no current window/pane to attach to.
+ */
+import type { TerminalBackend, SplitDirection } from '../types.js';
+/** argv that opens a new tmux window running the command in cwd. */
+export declare function tmuxTabArgv(cwd: string, command: string[]): string[];
+/** argv that splits the current tmux pane, running the command in cwd. */
+export declare function tmuxSplitArgv(cwd: string, command: string[], direction: SplitDirection): string[];
+export declare const tmuxBackend: TerminalBackend;

package/dist/lib/terminal/backends/tmux.js

@@ -0,0 +1,23 @@
+import { execOnly, iLoginShell } from '../shell.js';
+/** argv that opens a new tmux window running the command in cwd. */
+export function tmuxTabArgv(cwd, command) {
+    return ['tmux', 'new-window', '-c', cwd, iLoginShell(execOnly(command))];
+}
+/** argv that splits the current tmux pane, running the command in cwd. */
+export function tmuxSplitArgv(cwd, command, direction) {
+    const flag = direction === 'right' ? '-h' : '-v';
+    return ['tmux', 'split-window', flag, '-c', cwd, iLoginShell(execOnly(command))];
+}
+export const tmuxBackend = {
+    id: 'tmux',
+    label: 'tmux',
+    isAvailable(ctx) {
+        return Boolean(ctx.env.TMUX);
+    },
+    buildTab(cwd, command) {
+        return { argv: tmuxTabArgv(cwd, command) };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: tmuxSplitArgv(cwd, command, direction) };
+    },
+};

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

@@ -0,0 +1,39 @@
+/**
+ * The engine — turns requests into open surfaces.
+ *
+ * `specForRequest` and `buildRequests` are pure (planning); `openSurface` and
+ * `openSurfaces` add the side-effecting transport. A batch runs sequentially and
+ * staggered so a `split-right` lands in the tab that was just opened (the split
+ * targets the front pane).
+ */
+import type { Backend, EngineContext, LaunchRequest, LaunchResult, LaunchSpec } from './types.js';
+import { type Packing } from './policy.js';
+import { type HostResolver } from './transport.js';
+/** The concrete launch command for a request (pure — no side effects). */
+export declare function specForRequest(req: LaunchRequest): LaunchSpec;
+export interface OpenOptions {
+    resolveHost?: HostResolver;
+    ctx?: EngineContext;
+}
+/** Open a single surface for one request. Never throws — failures come back in the result. */
+export declare function openSurface(req: LaunchRequest, opts?: OpenOptions): Promise<LaunchResult>;
+/** One command to run as a surface. */
+export interface SurfaceItem {
+    cwd: string;
+    command: string[];
+}
+export interface BuildRequestsOptions {
+    backend: Backend;
+    host?: string;
+    packing?: Packing;
+}
+/** Turn a list of commands into layout-assigned requests (pure — the planning step). */
+export declare function buildRequests(items: SurfaceItem[], opts: BuildRequestsOptions): LaunchRequest[];
+export interface OpenManyOptions extends OpenOptions, BuildRequestsOptions {
+    staggerMs?: number;
+}
+/**
+ * Open many surfaces, applying the layout policy (default: two-per-tab).
+ * Sequential + staggered so each split follows the tab it splits.
+ */
+export declare function openSurfaces(items: SurfaceItem[], opts: OpenManyOptions): Promise<LaunchResult[]>;

package/dist/lib/terminal/engine.js

@@ -0,0 +1,54 @@
+import { BACKENDS } from './backends/index.js';
+import { planLayouts } from './policy.js';
+import { runSpec } from './transport.js';
+const DEFAULT_STAGGER_MS = 400;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The concrete launch command for a request (pure — no side effects). */
+export function specForRequest(req) {
+    const backend = BACKENDS[req.backend];
+    if (!backend)
+        throw new Error(`unknown backend: ${req.backend}`);
+    if (req.layout === 'tab')
+        return backend.buildTab(req.cwd, req.command);
+    return backend.buildSplit(req.cwd, req.command, req.layout === 'split-down' ? 'down' : 'right');
+}
+/** Open a single surface for one request. Never throws — failures come back in the result. */
+export async function openSurface(req, opts = {}) {
+    try {
+        // Both can throw: specForRequest on an unknown backend, runSpec when the
+        // SSH transport rejects an invalid --host target. Keep them inside the
+        // catch so a bad request degrades to a per-surface failure, never a throw.
+        const spec = specForRequest(req);
+        const res = await runSpec(spec, req.host, opts.resolveHost);
+        return { ok: res.ok, request: req, error: res.error };
+    }
+    catch (err) {
+        return { ok: false, request: req, error: err?.message ?? String(err) };
+    }
+}
+/** Turn a list of commands into layout-assigned requests (pure — the planning step). */
+export function buildRequests(items, opts) {
+    const layouts = planLayouts(items.length, opts.packing ?? 'two-per-tab');
+    return items.map((item, i) => ({
+        backend: opts.backend,
+        layout: layouts[i],
+        cwd: item.cwd,
+        command: item.command,
+        host: opts.host,
+    }));
+}
+/**
+ * Open many surfaces, applying the layout policy (default: two-per-tab).
+ * Sequential + staggered so each split follows the tab it splits.
+ */
+export async function openSurfaces(items, opts) {
+    const requests = buildRequests(items, opts);
+    const stagger = opts.staggerMs ?? DEFAULT_STAGGER_MS;
+    const results = [];
+    for (let i = 0; i < requests.length; i++) {
+        results.push(await openSurface(requests[i], opts));
+        if (i < requests.length - 1)
+            await sleep(stagger);
+    }
+    return results;
+}