@phnx-labs/agents-cli 1.20.91 → 1.20.92

package/dist/lib/session/render.js

@@ -13,6 +13,7 @@ import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
 import { redactSecrets } from '../redact.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from './digest.js';
+import { classifyBashCommand, unwrapCommand, bucketKey } from './bash-command.js';
 import { extractArtifacts, extractHooks, extractLinks, extractSkills } from './highlights.js';
 import { extractTodoProgressFromEvents } from './state.js';
 // ── Path helpers ──────────────────────────────────────────────────────────────
@@ -82,28 +83,6 @@ export function linkUrl(url, label) {
     return supportsHyperlinks() ? osc8(url, label) : label;
 }
 // ── Command grouping ──────────────────────────────────────────────────────────
-/**
- * Unwrap wrapper prefixes to find the actual executable.
- */
-export function unwrapCommand(cmd) {
-    const ssh = cmd.match(/^ssh\s+\S+\s+"(.+)"\s*(?:\|.*)?$/);
-    if (ssh)
-        return unwrapCommand(ssh[1]);
-    const lead = cmd.match(/^(?:sudo|env\s+\S+=\S+|time)\s+(.+)/);
-    if (lead)
-        return unwrapCommand(lead[1]);
-    // Strip shell-style leading env assignments: `PATH=/x CMD ...`, `FOO=bar BAR=baz CMD ...`
-    const shellEnv = cmd.match(/^(?:[A-Z_][A-Z0-9_]*=\S+\s+)+(\S.*)$/);
-    if (shellEnv)
-        return unwrapCommand(shellEnv[1]);
-    const cd = cmd.match(/^cd\s+\S+\s*&&\s*(.+)/);
-    if (cd)
-        return unwrapCommand(cd[1]);
-    const npx = cmd.match(/^npx\s+(.+)/);
-    if (npx)
-        return unwrapCommand(npx[1]);
-    return cmd;
-}
 /**
  * Normalize a command so trivial flag/pipe variations collapse to the same key.
  */
@@ -120,45 +99,35 @@ export function normalizeForDedup(cmd) {
     }
     return s.trim();
 }
-/** Command classification categories with signal levels for summary rendering. */
-const CATEGORIES = [
-    { name: 'Probes', match: t => ['ls', 'cat', 'head', 'tail', 'wc', 'stat', 'file', 'which', 'tree', 'pwd'].includes(t), signal: 'low' },
-    { name: 'Search', match: t => ['grep', 'rg', 'ag', 'fd', 'find'].includes(t), signal: 'low' },
-    { name: 'Build/test', match: t => ['make', 'cargo', 'pytest', 'go', 'bun', 'npm', 'pnpm', 'yarn', 'tsc', 'vitest', 'tsx', 'node', 'python', 'python3', 'jest'].includes(t), signal: 'high' },
-    { name: 'Install', match: t => ['brew', 'pip', 'apt', 'apk'].includes(t), signal: 'high' },
-    { name: 'VCS', match: t => ['git', 'gh'].includes(t), signal: 'mid' },
-    { name: 'HTTP', match: t => ['curl', 'wget', 'rush', 'http'].includes(t), signal: 'mid' },
-    { name: 'Remote', match: t => ['ssh', 'scp', 'rsync'].includes(t), signal: 'mid' },
-    { name: 'Shell', match: t => ['rm', 'mv', 'cp', 'mkdir', 'touch', 'echo', 'printf', 'chmod', 'ln', 'awk', 'sed', 'tee', 'xargs', 'for'].includes(t), signal: 'low' },
-    { name: 'Wait', match: t => ['sleep', 'wait'].includes(t), signal: 'low' },
-];
-/** CLI tools whose subcommand (second token) is included in the bucket key. */
-const TWO_LEVEL_TOKENS = new Set([
-    'git', 'gh', 'bun', 'npm', 'cargo', 'docker', 'kubectl', 'rush', 'openclaw', 'pnpm', 'yarn',
-]);
-/**
- * Return the bucket key for a command (used for grouping within a category).
- */
-export function bucketKey(cmd) {
-    const unwrapped = unwrapCommand(cmd);
-    const tokens = unwrapped.trim().split(/\s+/);
-    const first = tokens[0] ?? 'other';
-    const isRemote = cmd.trim().startsWith('ssh ') || cmd.trim().startsWith('scp ');
-    if (TWO_LEVEL_TOKENS.has(first) && tokens[1]) {
-        const key = `${first} ${tokens[1]}`;
-        return isRemote ? `ssh\u2192${key}` : key;
-    }
-    return isRemote ? `ssh\u2192${first}` : first;
-}
+// Re-export the shared classifier/bucketing for callers in this module's surface.
+// `bucketKey` is the single source of truth in bash-command.ts (correct subcommand
+// scan + `ssh\u2192` remote prefix); render must not keep a divergent copy.
+export { unwrapCommand, bucketKey };
+const CATEGORY_NAMES = {
+    vcs: 'VCS',
+    'build-test': 'Build/test',
+    install: 'Install',
+    remote: 'Remote',
+    http: 'HTTP',
+    media: 'Media',
+    upscaling: 'Upscaling',
+    metadata: 'Metadata',
+    probe: 'Probes',
+    search: 'Search',
+    shell: 'Shell',
+    wait: 'Wait',
+    other: 'Other',
+};
 function categoryOf(cmd) {
     const rawFirst = cmd.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
     // Remote wrappers: classify as Remote regardless of inner command.
     if (['ssh', 'scp', 'rsync'].includes(rawFirst)) {
-        return CATEGORIES.find(c => c.name === 'Remote') ?? null;
+        return { name: 'Remote', signal: 'mid' };
     }
-    const unwrapped = unwrapCommand(cmd);
-    const first = unwrapped.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
-    return CATEGORIES.find(c => c.match(first)) ?? null;
+    const info = classifyBashCommand(cmd);
+    if (info.category === 'other')
+        return null;
+    return { name: CATEGORY_NAMES[info.category], signal: info.signal };
 }
 /**
  * Collapse consecutive same-normalized commands within a 60-second window

package/dist/lib/ssh-exec.d.ts

@@ -73,6 +73,12 @@ export declare function sshExec(target: string, remoteCmd: string, opts?: SshExe
 /**
  * Async variant of {@link sshExec}. Same hardened argv composition, but uses
  * child_process.spawn so fleet fan-outs can probe multiple hosts concurrently.
+ *
+ * A timeout-bearing call uses a fresh ssh connection (`multiplex: false`) even
+ * when the caller requests multiplexing: a control-master outlives the local
+ * client, so killing the local ssh process on timeout would leave the remote
+ * command running. With a direct connection, terminating the local child tears
+ * down the remote side (RUSH-2114).
  */
 export declare function sshExecAsync(target: string, remoteCmd: string, opts?: SshExecOptions): Promise<SshExecResult>;
 export interface SshExecRawResult {

package/dist/lib/ssh-exec.js

@@ -128,10 +128,19 @@ export function sshExec(target, remoteCmd, opts = {}) {
 /**
  * Async variant of {@link sshExec}. Same hardened argv composition, but uses
  * child_process.spawn so fleet fan-outs can probe multiple hosts concurrently.
+ *
+ * A timeout-bearing call uses a fresh ssh connection (`multiplex: false`) even
+ * when the caller requests multiplexing: a control-master outlives the local
+ * client, so killing the local ssh process on timeout would leave the remote
+ * command running. With a direct connection, terminating the local child tears
+ * down the remote side (RUSH-2114).
  */
 export function sshExecAsync(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
-    const mux = opts.multiplex === false ? [] : controlOpts();
+    // Control-master connections defeat local timeouts — the master keeps the
+    // remote command alive after we kill the client. Force a fresh connection
+    // whenever the caller asked for a timeout so the timeout actually stops work.
+    const mux = opts.multiplex === false || opts.timeoutMs ? [] : controlOpts();
     const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), target, remoteCmd];
     return new Promise((resolve) => {
         const child = spawn('ssh', args, {

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

@@ -44,6 +44,7 @@ export declare const loadExport: ModuleLoader;
 export declare const loadPackages: ModuleLoader;
 export declare const loadRoutines: ModuleLoader;
 export declare const loadMonitors: ModuleLoader;
+export declare const loadProjects: ModuleLoader;
 export declare const loadRun: ModuleLoader;
 export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;

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

@@ -22,6 +22,7 @@ export const loadExport = async () => (await import('../../commands/export.js'))
 export const loadPackages = async () => (await import('../../commands/packages.js')).registerPackagesCommands;
 export const loadRoutines = async () => (await import('../../commands/routines.js')).registerRoutinesCommands;
 export const loadMonitors = async () => (await import('../../commands/monitors.js')).registerMonitorsCommands;
+export const loadProjects = async () => (await import('../../commands/projects.js')).registerProjectsCommands;
 export const loadRun = async () => (await import('../../commands/exec.js')).registerRunCommand;
 export const loadFork = async () => (await import('../../commands/fork.js')).registerForkCommand;
 export const loadDefaults = async () => (await import('../../commands/defaults.js')).registerDefaultsCommands;
@@ -134,6 +135,7 @@ export const COMMAND_LOADERS = {
     install: [loadPackages],
     routines: [loadRoutines],
     monitors: [loadMonitors],
+    projects: [loadProjects],
     run: [loadRun],
     fork: [loadFork],
     defaults: [loadDefaults],

package/dist/lib/state.d.ts

@@ -109,6 +109,8 @@ export declare function getCacheDir(): string;
 export declare function getPackagesDir(): string;
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export declare function getRoutinesDir(): string;
+/** Path to named project definitions (~/.agents/projects/). */
+export declare function getProjectsDir(): string;
 /**
  * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
  * one-off triggers for agents/workflows/commands/routines, layered the same way

package/dist/lib/state.js

@@ -88,6 +88,9 @@ const WEBHOOKS_DIR = path.join(USER_AGENTS_DIR, 'webhooks');
 // monitor is a routine whose trigger is a watched source instead of a clock.
 const MONITORS_DIR = path.join(USER_AGENTS_DIR, 'monitors');
 const TEAMS_DIR = path.join(USER_AGENTS_DIR, 'teams');
+// Named project definitions (the layer above the --project convention). Sibling
+// of ROUTINES_DIR/TEAMS_DIR: hand-editable YAML, synced across machines by push/pull.
+const PROJECTS_DIR = path.join(USER_AGENTS_DIR, 'projects');
 // History bucket (durable).
 const SESSIONS_DIR = path.join(HISTORY_DIR, 'sessions');
 const SESSIONS_DB_PATH = path.join(SESSIONS_DIR, 'sessions.db');
@@ -311,6 +314,8 @@ export function getCacheDir() { return CACHE_DIR; }
 export function getPackagesDir() { return PACKAGES_DIR; }
 /** Path to routine YAML definitions (~/.agents/routines/). */
 export function getRoutinesDir() { return process.env.AGENTS_ROUTINES_DIR ?? ROUTINES_DIR; }
+/** Path to named project definitions (~/.agents/projects/). */
+export function getProjectsDir() { return process.env.AGENTS_PROJECTS_DIR ?? PROJECTS_DIR; }
 /**
  * Path to webhook handler YAML definitions (~/.agents/webhooks/). Handlers are
  * one-off triggers for agents/workflows/commands/routines, layered the same way

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

@@ -6,7 +6,15 @@ import { itermBackend } from './iterm.js';
 import { ghosttyBackend } from './ghostty.js';
 import { tmuxBackend } from './tmux.js';
 import { vscodiumAgentBackend } from './vscodium-agent.js';
-/** All known interactive backends, keyed by id. */
+import { terminalAppBackend } from './terminal-app.js';
+/**
+ * All known interactive backends, keyed by id.
+ *
+ * Insertion order is the preference order `availableBackends` returns, and
+ * `terminal` (Terminal.app) sits LAST deliberately: it is the every-Mac floor, so
+ * a caller that falls back to the first available backend still prefers a real
+ * terminal the user chose to install.
+ */
 export declare const BACKENDS: Record<Backend, TerminalBackend>;
 /**
  * The backend for the terminal the CLI is currently running in, or null if we
@@ -16,4 +24,4 @@ export declare const BACKENDS: Record<Backend, TerminalBackend>;
 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, vscodiumAgentBackend };
+export { itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend, terminalAppBackend };

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

@@ -2,12 +2,21 @@ import { itermBackend } from './iterm.js';
 import { ghosttyBackend } from './ghostty.js';
 import { tmuxBackend } from './tmux.js';
 import { vscodiumAgentBackend } from './vscodium-agent.js';
-/** All known interactive backends, keyed by id. */
+import { terminalAppBackend } from './terminal-app.js';
+/**
+ * All known interactive backends, keyed by id.
+ *
+ * Insertion order is the preference order `availableBackends` returns, and
+ * `terminal` (Terminal.app) sits LAST deliberately: it is the every-Mac floor, so
+ * a caller that falls back to the first available backend still prefers a real
+ * terminal the user chose to install.
+ */
 export const BACKENDS = {
     iterm: itermBackend,
     ghostty: ghosttyBackend,
     tmux: tmuxBackend,
     'vscodium-agent': vscodiumAgentBackend,
+    terminal: terminalAppBackend,
 };
 /**
  * The backend for the terminal the CLI is currently running in, or null if we
@@ -22,10 +31,13 @@ export function detectCurrentBackend(ctx) {
         return 'iterm';
     if (term.includes('ghostty'))
         return 'ghostty';
+    // Terminal.app sets TERM_PROGRAM=Apple_Terminal.
+    if (term.includes('apple_terminal'))
+        return 'terminal';
     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, vscodiumAgentBackend };
+export { itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend, terminalAppBackend };

package/dist/lib/terminal/backends/terminal-app.d.ts

@@ -0,0 +1,13 @@
+import type { TerminalBackend } from '../types.js';
+/**
+ * AppleScript that opens a Terminal.app tab running the command.
+ *
+ * `do script` with no `in` target opens a NEW window; with a front window
+ * present, `tell application "System Events" to keystroke "t"` would be the only
+ * way to force a tab, and that needs an Accessibility grant. So: a window when
+ * none exists, otherwise `do script … in front window`, which Terminal renders
+ * as a new tab of that window when its "New tabs" setting is on and a new
+ * window otherwise. Either way the command runs in a fresh, visible surface.
+ */
+export declare function terminalAppTabScript(cwd: string, command: string[]): string;
+export declare const terminalAppBackend: TerminalBackend;

package/dist/lib/terminal/backends/terminal-app.js

@@ -0,0 +1,73 @@
+/**
+ * Terminal.app backend — drives macOS Terminal via AppleScript (`osascript`).
+ *
+ * This is the floor of the backend list: every Mac has Terminal.app, so a GUI
+ * caller that can name no better terminal still gets a surface. It is also what
+ * the menu bar's "New Session" always used before the engine took that path
+ * over, so registering it keeps a Terminal-only Mac working exactly as it did.
+ *
+ * Terminal.app has no scriptable split — `do script` only ever makes a tab (or a
+ * window). A split request therefore opens a TAB, which is stated here and in
+ * `buildSplit` rather than silently pretending the pane happened.
+ */
+import * as fs from 'fs';
+import { appleScriptStr } from '../quote.js';
+import { loginExec, iLoginShell } from '../shell.js';
+const TERMINAL_APP = '/System/Applications/Utilities/Terminal.app';
+const TERMINAL_APP_LEGACY = '/Applications/Utilities/Terminal.app';
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * AppleScript that opens a Terminal.app tab running the command.
+ *
+ * `do script` with no `in` target opens a NEW window; with a front window
+ * present, `tell application "System Events" to keystroke "t"` would be the only
+ * way to force a tab, and that needs an Accessibility grant. So: a window when
+ * none exists, otherwise `do script … in front window`, which Terminal renders
+ * as a new tab of that window when its "New tabs" setting is on and a new
+ * window otherwise. Either way the command runs in a fresh, visible surface.
+ */
+export function terminalAppTabScript(cwd, command) {
+    const cmd = appleScriptStr(iLoginShell(loginExec(cwd, command)));
+    return [
+        'tell application "Terminal"',
+        '  activate',
+        '  if (count of windows) is 0 then',
+        `    do script ${cmd}`,
+        '  else',
+        `    do script ${cmd} in front window`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+export const terminalAppBackend = {
+    id: 'terminal',
+    label: 'Terminal',
+    /**
+     * Terminal.app is scriptable only from a session that can reach the GUI login
+     * — an `osascript` fired over plain SSH gets "Application isn't running" — so
+     * an SSH-hosted context reports it unavailable rather than launching into a
+     * window nobody can see. (A launchd GUI agent like the menu bar helper has no
+     * SSH_* vars and is available.)
+     */
+    isAvailable(ctx) {
+        if (ctx.platform !== 'darwin')
+            return false;
+        if (ctx.env.SSH_CONNECTION || ctx.env.SSH_TTY)
+            return false;
+        return appExists(TERMINAL_APP) || appExists(TERMINAL_APP_LEGACY);
+    },
+    buildTab(cwd, command) {
+        return { argv: ['osascript', '-e', terminalAppTabScript(cwd, command)] };
+    },
+    /** Terminal.app cannot split by script — a split request opens a tab instead. */
+    buildSplit(cwd, command, _direction) {
+        return { argv: ['osascript', '-e', terminalAppTabScript(cwd, command)] };
+    },
+};

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

@@ -8,7 +8,8 @@
  */
 export type { Backend, SplitDirection, Layout, EngineContext, LaunchSpec, LaunchRequest, LaunchResult, TerminalBackend, } from './types.js';
 export { currentContext } from './types.js';
-export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend } from './backends/index.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend, terminalAppBackend } from './backends/index.js';
+export { SESSION_HOST_BACKENDS, backendFromSessions, resolveLaunchBackend, describeBackendChoice, type SessionHostSample, type BackendSource, type LaunchBackendChoice, } from './preferred.js';
 export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS, type EditorVariant } from './backends/vscodium-agent.js';
 export { planLayouts, type Packing } from './policy.js';
 export { specForRequest, buildRequests, openSurface, openSurfaces, type OpenOptions, type OpenManyOptions, type BuildRequestsOptions, type SurfaceItem, } from './engine.js';

package/dist/lib/terminal/index.js

@@ -1,5 +1,6 @@
 export { currentContext } from './types.js';
-export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend } from './backends/index.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend, terminalAppBackend } from './backends/index.js';
+export { SESSION_HOST_BACKENDS, backendFromSessions, resolveLaunchBackend, describeBackendChoice, } from './preferred.js';
 export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS } from './backends/vscodium-agent.js';
 export { planLayouts } from './policy.js';
 export { specForRequest, buildRequests, openSurface, openSurfaces, } from './engine.js';

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

@@ -0,0 +1,89 @@
+/**
+ * Which terminal to launch a NEW surface into, for callers that aren't in one.
+ *
+ * `detectCurrentBackend` answers this from `$TMUX` / `$TERM_PROGRAM`, which is
+ * correct for a command the user typed in a terminal — and useless to a GUI
+ * caller. The menu-bar helper is launched by launchd with no terminal in its
+ * ancestry, so it used to hardcode AppleScript against Terminal.app and opened
+ * every "New Session" there no matter what the user actually works in.
+ *
+ * The signal it was missing is already on disk: `agents sessions --active`
+ * attributes every live session to its host app (`ActiveSession.host`, resolved
+ * by walking the process table in session/active.ts). So the terminal the user
+ * demonstrably runs agents in is the terminal a new session should open in —
+ * that's what this module resolves, and it is the reason the menu bar now opens
+ * Ghostty for a Ghostty user and iTerm for an iTerm user.
+ *
+ * Resolution order (each step is skipped when it names nothing DRIVABLE here):
+ *   1. the terminal this process is running in   -> 'current-terminal'
+ *   2. the host app of the most recent live session -> 'active-session'
+ *   3. the first available backend (Terminal.app is the every-Mac floor) -> 'available'
+ */
+import type { Backend, EngineContext } from './types.js';
+/**
+ * `ActiveSession.host` -> the backend that can open a new surface in it.
+ *
+ * Deliberately partial. A host is listed ONLY when the engine can really drive
+ * it, because a wrong mapping opens the wrong app and looks like success:
+ *   - `code` / `cursor` / `windsurf` are absent even though the engine has an
+ *     editor backend — the registered `vscodium-agent` is bound to the VSCodium
+ *     variant (backends/vscodium-agent.ts: `EDITOR_VARIANTS[0]`), so mapping
+ *     Cursor to it would open VSCodium instead of Cursor.
+ *   - `warp` / `kitty` / `wezterm` / `alacritty` / `hyper` / `screen` are absent
+ *     because no backend drives them yet.
+ * An unmapped host isn't an error — resolution simply moves to the next session,
+ * and ultimately to the available-backend floor.
+ */
+export declare const SESSION_HOST_BACKENDS: Readonly<Record<string, Backend>>;
+/** The subset of an ActiveSession this resolver reads. */
+export interface SessionHostSample {
+    host?: string;
+    /**
+     * For a tmux-hosted session: the app its attached tmux client is in
+     * (`ActiveSession.viewingIn.app`). This is load-bearing, not a nicety —
+     * `agents run` wraps interactive runs in tmux, so a session the user started
+     * in Ghostty is attributed `host: 'tmux'` and the terminal it is actually
+     * displayed in is only knowable through the attached client. Takes precedence
+     * over `host`, which for these sessions names the multiplexer, not a terminal.
+     */
+    viewingApp?: string;
+    lastActivityMs?: number;
+    startedAtMs?: number;
+}
+/** Where the chosen backend came from — reported so a caller can say why. */
+export type BackendSource = 'forced' | 'current-terminal' | 'active-session' | 'available';
+export interface LaunchBackendChoice {
+    backend: Backend;
+    source: BackendSource;
+    /** The `ActiveSession.host` that selected it, when source is 'active-session'. */
+    host?: string;
+}
+/**
+ * Injection seam so the PRECEDENCE is testable without the machine's installed
+ * apps. `isAvailable` for iterm/ghostty/terminal probes `/Applications`, so a
+ * test that just passes `platform: 'darwin'` silently depends on the host having
+ * those apps — it passes on a dev Mac and fails on a Linux CI runner. Same shape
+ * as `ViewingInDeps` in session/viewing-in.ts.
+ */
+export interface BackendResolveDeps {
+    /** Defaults to the real backend availability probe. */
+    isAvailable?: (backend: Backend, ctx: EngineContext) => boolean;
+}
+/**
+ * The backend for the terminal the user's most recent live session runs in, or
+ * null when no live session names a host this engine can drive. Pure — the
+ * caller supplies the sessions, so the precedence is unit-testable without a
+ * process table.
+ */
+export declare function backendFromSessions(sessions: SessionHostSample[], ctx: EngineContext, deps?: BackendResolveDeps): {
+    backend: Backend;
+    host: string;
+} | null;
+/**
+ * Resolve the terminal to open a new surface in. Pure. Returns null when this
+ * machine has no drivable terminal at all (Linux with no tmux, an SSH session),
+ * which callers must handle — never a guess that silently goes nowhere.
+ */
+export declare function resolveLaunchBackend(ctx: EngineContext, sessions?: SessionHostSample[], deps?: BackendResolveDeps): LaunchBackendChoice | null;
+/** One line explaining a choice, for the `agents run --terminal` preamble. */
+export declare function describeBackendChoice(choice: LaunchBackendChoice): string;

package/dist/lib/terminal/preferred.js

@@ -0,0 +1,87 @@
+import { BACKENDS, detectCurrentBackend } from './backends/index.js';
+/**
+ * `ActiveSession.host` -> the backend that can open a new surface in it.
+ *
+ * Deliberately partial. A host is listed ONLY when the engine can really drive
+ * it, because a wrong mapping opens the wrong app and looks like success:
+ *   - `code` / `cursor` / `windsurf` are absent even though the engine has an
+ *     editor backend — the registered `vscodium-agent` is bound to the VSCodium
+ *     variant (backends/vscodium-agent.ts: `EDITOR_VARIANTS[0]`), so mapping
+ *     Cursor to it would open VSCodium instead of Cursor.
+ *   - `warp` / `kitty` / `wezterm` / `alacritty` / `hyper` / `screen` are absent
+ *     because no backend drives them yet.
+ * An unmapped host isn't an error — resolution simply moves to the next session,
+ * and ultimately to the available-backend floor.
+ */
+export const SESSION_HOST_BACKENDS = Object.freeze({
+    iterm: 'iterm',
+    ghostty: 'ghostty',
+    terminal: 'terminal',
+    tmux: 'tmux',
+    codium: 'vscodium-agent',
+});
+/** Most recent first. Falls back to start time, then to the given order. */
+function byRecency(a, b) {
+    const at = a.lastActivityMs ?? a.startedAtMs ?? 0;
+    const bt = b.lastActivityMs ?? b.startedAtMs ?? 0;
+    return bt - at;
+}
+const realIsAvailable = (backend, ctx) => BACKENDS[backend].isAvailable(ctx);
+/**
+ * The backend for the terminal the user's most recent live session runs in, or
+ * null when no live session names a host this engine can drive. Pure — the
+ * caller supplies the sessions, so the precedence is unit-testable without a
+ * process table.
+ */
+export function backendFromSessions(sessions, ctx, deps = {}) {
+    const isAvailable = deps.isAvailable ?? realIsAvailable;
+    for (const s of [...sessions].sort(byRecency)) {
+        // The app an attached tmux client is in beats the multiplexer name.
+        const host = s.viewingApp ?? s.host;
+        if (!host)
+            continue;
+        // hasOwn, not a bare index: the host is data, and `SESSION_HOST_BACKENDS['constructor']`
+        // would otherwise hand back a prototype member that BACKENDS cannot key on.
+        if (!Object.hasOwn(SESSION_HOST_BACKENDS, host))
+            continue;
+        const backend = SESSION_HOST_BACKENDS[host];
+        if (!backend)
+            continue;
+        if (!isAvailable(backend, ctx))
+            continue;
+        return { backend, host };
+    }
+    return null;
+}
+/**
+ * Resolve the terminal to open a new surface in. Pure. Returns null when this
+ * machine has no drivable terminal at all (Linux with no tmux, an SSH session),
+ * which callers must handle — never a guess that silently goes nowhere.
+ */
+export function resolveLaunchBackend(ctx, sessions = [], deps = {}) {
+    const isAvailable = deps.isAvailable ?? realIsAvailable;
+    const current = detectCurrentBackend(ctx);
+    if (current && isAvailable(current, ctx)) {
+        return { backend: current, source: 'current-terminal' };
+    }
+    const fromSession = backendFromSessions(sessions, ctx, deps);
+    if (fromSession) {
+        return { backend: fromSession.backend, source: 'active-session', host: fromSession.host };
+    }
+    const first = Object.keys(BACKENDS).find((b) => isAvailable(b, ctx));
+    return first ? { backend: first, source: 'available' } : null;
+}
+/** One line explaining a choice, for the `agents run --terminal` preamble. */
+export function describeBackendChoice(choice) {
+    const label = BACKENDS[choice.backend].label;
+    switch (choice.source) {
+        case 'forced':
+            return `${label} (you asked for it)`;
+        case 'current-terminal':
+            return `${label} (the terminal you're in)`;
+        case 'active-session':
+            return `${label} (where your ${choice.host} sessions run)`;
+        case 'available':
+            return `${label} (no running session named a terminal)`;
+    }
+}

package/dist/lib/terminal/run-surface.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `agents run … --terminal` — re-open this exact run as a tab in a real terminal.
+ *
+ * A GUI caller (the menu bar's "New Session") cannot host a TUI, so it has to
+ * hand the run to a terminal. It used to do that by hardcoding AppleScript at
+ * Terminal.app; now it appends `--terminal` and the CLI decides WHICH terminal
+ * from the user's own live sessions (preferred.ts) and opens the tab through the
+ * launch engine — the same engine `sessions resume` and `sessions focus` use.
+ *
+ * The re-invocation is the caller's own argv with the `--terminal` flag removed,
+ * so every other flag (`--mode`, `--cwd`, a `--` passthrough) rides along
+ * untouched and there is no second place that knows how to spell a run.
+ */
+import type { Backend, EngineContext } from './types.js';
+import type { ActiveSession } from '../session/active.js';
+import { type LaunchBackendChoice, type SessionHostSample } from './preferred.js';
+/** Backends a user may name in `--terminal <backend>`. */
+export declare const TERMINAL_FLAG_BACKENDS: Backend[];
+/**
+ * Validate a `--terminal <value>`. Returns the backend, or an error message
+ * naming the valid ids — never a silent fallback to auto-detection, which would
+ * open a terminal the user did not ask for.
+ */
+export declare function parseTerminalFlag(value: unknown): {
+    backend?: Backend;
+    error?: string;
+};
+/**
+ * The argv to re-invoke, with `--terminal` (and the value commander consumed for
+ * it) removed. `consumedValue` is the parsed option value when it is a string —
+ * that is the only token after the flag that belongs to it, so a prompt or a
+ * following flag is never eaten.
+ */
+export declare function stripTerminalFlag(argv: string[], consumedValue?: string): string[];
+/** `agents run …` as a shell-safe command line for the surface to exec. */
+export declare function buildRunCommand(argv: string[]): string[];
+/**
+ * Turn live sessions into the samples the resolver reads, filling in the app
+ * each tmux-hosted session is currently VIEWED in.
+ *
+ * This step is what makes detection work for the common case: `agents run`
+ * wraps interactive runs in tmux, so a session the user started in Ghostty is
+ * attributed `host: 'tmux'` on the discovery path and would otherwise name no
+ * terminal at all. `resolveViewingIn` walks the attached tmux client's pid up to
+ * its host app — the same resolver `agents sessions` uses to print
+ * "viewing in Ghostty tab 2". Sessions that are detached (no client attached)
+ * legitimately have no viewer and keep their `tmux` host.
+ *
+ * One inherited nuance: `resolveViewingIn` labels a client whose app it cannot
+ * identify `'terminal'` (viewing-in.ts:87), so a tmux session viewed from an
+ * unrecognized emulator resolves to Terminal.app rather than falling through.
+ * That lands on the same every-Mac floor the fallback chain ends at anyway, so
+ * it costs nothing here — but it is a default, not a detection.
+ *
+ * Best-effort: any probe failure degrades to the plain host, never throws.
+ */
+export declare function toHostSamples(sessions: ActiveSession[]): Promise<SessionHostSample[]>;
+export interface OpenRunSurfaceParams {
+    /** This process's argv after the program name (i.e. `['run','claude',…]`). */
+    argv: string[];
+    /** The parsed `--terminal` value, when the user named a backend. */
+    forced?: Backend;
+    /** The value commander consumed for `--terminal`, so it can be stripped. */
+    consumedValue?: string;
+    cwd: string;
+    /** Live sessions, used to detect the terminal the user actually works in. */
+    sessions: SessionHostSample[];
+    ctx: EngineContext;
+}
+export interface OpenRunSurfaceResult {
+    ok: boolean;
+    choice?: LaunchBackendChoice;
+    /** Human line describing the terminal that was chosen. */
+    description?: string;
+    error?: string;
+}
+/**
+ * Open the run as a tab in the resolved terminal. Never throws — a failure comes
+ * back as `ok: false` with the reason, so the caller can tell the user rather
+ * than exiting silently.
+ */
+export declare function openRunInTerminal(params: OpenRunSurfaceParams): Promise<OpenRunSurfaceResult>;