@phnx-labs/agents-cli 1.20.90 → 1.20.92

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');
@@ -116,6 +119,8 @@ const CLOUD_DIR = path.join(CACHE_DIR, 'cloud');
 const DRIVE_DIR = path.join(CACHE_DIR, 'drive');
 const TERMINALS_DIR = path.join(CACHE_DIR, 'terminals');
 const LOGS_DIR = path.join(CACHE_DIR, 'logs');
+/** Disposable performance samples (~/.agents/.cache/perf/) — safe to wipe. */
+const PERF_DIR = path.join(CACHE_DIR, 'perf');
 const RUNTIME_STATE_DIR = path.join(CACHE_DIR, 'state');
 const COMPANION_CACHE_DIR = path.join(CACHE_DIR, 'companion');
 const BROWSER_RUNTIME_DIR = path.join(CACHE_DIR, 'browser');
@@ -309,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
@@ -436,6 +443,15 @@ export function getCloudDir() { return CLOUD_DIR; }
 export function getTerminalsDir() { return TERMINALS_DIR; }
 /** Path to runtime logs (~/.agents/.cache/logs/). */
 export function getLogsDir() { return LOGS_DIR; }
+/**
+ * Path to disposable performance samples (~/.agents/.cache/perf/).
+ * Holds `perf.db` + a hook-shim spool. Loss is acceptable — wipe freely.
+ */
+export function getPerfDir() { return PERF_DIR; }
+/** Path to the perf SQLite warehouse (~/.agents/.cache/perf/perf.db). */
+export function getPerfDbPath() { return path.join(PERF_DIR, 'perf.db'); }
+/** Path to the hook-shim NDJSON spool drained into perf.db on open. */
+export function getPerfSpoolPath() { return path.join(PERF_DIR, 'spool.jsonl'); }
 /** Path to per-process runtime state (~/.agents/.cache/state/). */
 export function getRuntimeStateDir() { return RUNTIME_STATE_DIR; }
 /** Path to companion-extension scratch (~/.agents/.cache/companion/). */

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>;

package/dist/lib/terminal/run-surface.js

@@ -0,0 +1,146 @@
+import { BACKENDS } from './backends/index.js';
+import { openSurface } from './engine.js';
+import { getCliLaunch } from '../cli-entry.js';
+import { shellQuote } from './quote.js';
+import { resolveLaunchBackend, describeBackendChoice, } from './preferred.js';
+/** Backends a user may name in `--terminal <backend>`. */
+export const TERMINAL_FLAG_BACKENDS = Object.keys(BACKENDS);
+/**
+ * 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 function parseTerminalFlag(value) {
+    if (value === undefined || value === true || value === '')
+        return {};
+    const raw = String(value);
+    if (TERMINAL_FLAG_BACKENDS.includes(raw))
+        return { backend: raw };
+    // `--terminal [backend]` takes an OPTIONAL value, and commander assigns the
+    // next non-option token to it — so `agents run claude --terminal "fix the bug"`
+    // lands the prompt here. Say that, or the user just sees their prompt called a
+    // bad backend name and has no idea why.
+    const looksLikeAPrompt = /\s/.test(raw) || raw.length > 24;
+    const hint = looksLikeAPrompt
+        ? ` That looks like a prompt: put it BEFORE the flag — agents run <agent> "${raw.length > 40 ? `${raw.slice(0, 40)}…` : raw}" --terminal.`
+        : '';
+    return {
+        error: `Unknown --terminal backend '${raw}'. Use one of: ${TERMINAL_FLAG_BACKENDS.join(', ')} (or pass --terminal alone to auto-detect).${hint}`,
+    };
+}
+/**
+ * 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 function stripTerminalFlag(argv, consumedValue) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        // Everything past a bare `--` is forwarded verbatim to the agent's own CLI
+        // (`agents run kimi -- --terminal`), so it is not ours to rewrite.
+        if (tok === '--') {
+            out.push(...argv.slice(i));
+            break;
+        }
+        if (tok === '--terminal') {
+            if (consumedValue !== undefined && argv[i + 1] === consumedValue)
+                i++;
+            continue;
+        }
+        if (tok.startsWith('--terminal='))
+            continue;
+        out.push(tok);
+    }
+    return out;
+}
+/** `agents run …` as a shell-safe command line for the surface to exec. */
+export function buildRunCommand(argv) {
+    const { command, args } = getCliLaunch(argv);
+    return [command, ...args].map(shellQuote);
+}
+/**
+ * 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 async function toHostSamples(sessions) {
+    const samples = sessions.map((s) => ({
+        host: s.host,
+        lastActivityMs: s.lastActivityMs,
+        startedAtMs: s.startedAtMs,
+    }));
+    const tmuxIdx = sessions
+        .map((s, i) => ({ s, i }))
+        .filter(({ s }) => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
+    if (tmuxIdx.length === 0)
+        return samples;
+    try {
+        const { enumerateGhosttyTabs } = await import('../session/ghostty-tabs.js');
+        const { mapPanesToTargets, listClients } = await import('../tmux/session.js');
+        const { resolveViewingIn } = await import('../session/viewing-in.js');
+        // One Ghostty enumeration shared across sockets, as the sessions renderer does.
+        const ghosttySurfaces = await enumerateGhosttyTabs();
+        const sockets = new Set(tmuxIdx.map(({ s }) => s.provenance.mux.socket));
+        for (const socket of sockets) {
+            const paneToTarget = await mapPanesToTargets(socket);
+            if (paneToTarget.size === 0)
+                continue;
+            const clients = await listClients(socket);
+            for (const { s, i } of tmuxIdx) {
+                if (s.provenance.mux.socket !== socket)
+                    continue;
+                const viewing = await resolveViewingIn(s, clients, { paneToTarget, ghosttySurfaces });
+                if (viewing)
+                    samples[i].viewingApp = viewing.app;
+            }
+        }
+    }
+    catch {
+        // tmux/Ghostty probes are best-effort; fall back to the plain host values.
+    }
+    return samples;
+}
+/**
+ * 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 async function openRunInTerminal(params) {
+    const choice = params.forced
+        ? { backend: params.forced, source: 'forced' }
+        : resolveLaunchBackend(params.ctx, params.sessions);
+    if (!choice) {
+        return {
+            ok: false,
+            error: 'No terminal this machine can drive (need iTerm, Ghostty, Terminal.app, VSCodium, or a tmux session). Run without --terminal.',
+        };
+    }
+    if (params.forced && !BACKENDS[choice.backend].isAvailable(params.ctx)) {
+        return { ok: false, error: `--terminal ${choice.backend} is not available here.` };
+    }
+    const command = buildRunCommand(stripTerminalFlag(params.argv, params.consumedValue));
+    const result = await openSurface({
+        backend: choice.backend,
+        layout: 'tab',
+        cwd: params.cwd,
+        command,
+    });
+    return { ok: result.ok, choice, description: describeBackendChoice(choice), error: result.error };
+}

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

@@ -8,7 +8,7 @@
  * 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';
+export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent' | 'terminal';
 /** 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. */

package/dist/lib/types.d.ts

@@ -62,7 +62,7 @@ export interface BudgetConfig {
     require_confirm_over?: number;
 }
 /** Preview features that users can opt into via `agents beta`. */
-export type BetaFeatureName = 'drive' | 'factory' | 'session-sync';
+export type BetaFeatureName = 'drive' | 'factory' | 'session-sync' | 'projects';
 /** Subset of chalk color names used for agent-specific terminal output. */
 export type ChalkColor = 'magenta' | 'green' | 'blue' | 'cyan' | 'yellowBright' | 'redBright' | 'whiteBright' | 'blueBright' | 'greenBright' | 'magentaBright' | 'cyanBright';
 /** Static configuration for a single agent -- paths, capabilities, and format conventions. */