@phnx-labs/agents-cli 1.20.91 → 1.20.93

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/sqlite.js

@@ -14,11 +14,38 @@
 import { createRequire } from 'module';
 const isBun = typeof globalThis.Bun !== 'undefined';
 const require = createRequire(import.meta.url);
+// node:sqlite emits a process-level ExperimentalWarning the first time it loads.
+// The packaged CLI launches Node with --no-warnings=ExperimentalWarning, but a
+// direct `node dist/...` run (and vitest's subprocesses) does not, so the warning
+// would leak onto stderr and break any command whose --json output is asserted to
+// be clean. Suppress only that single warning for the duration of the load; every
+// other warning passes through untouched.
+function loadNodeSqlite() {
+    const original = process.emitWarning;
+    const filtered = ((warning, ...rest) => {
+        const name = warning instanceof Error
+            ? warning.name
+            : typeof rest[0] === 'string'
+                ? rest[0]
+                : rest[0]?.type;
+        const message = warning instanceof Error ? warning.message : warning;
+        if (name === 'ExperimentalWarning' && /SQLite/i.test(String(message ?? '')))
+            return;
+        original.call(process, warning, ...rest);
+    });
+    process.emitWarning = filtered;
+    try {
+        return require('node:sqlite');
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
 // Keep Node on createRequire() so Vitest doesn't try to prebundle the built-in
 // sqlite module as a userland package during test collection.
 const sqliteMod = isBun
     ? await import('bun:sqlite')
-    : require('node:sqlite');
+    : loadNodeSqlite();
 // bun:sqlite exports `Database`; node:sqlite exports `DatabaseSync`.
 const NativeDatabase = sqliteMod.Database
     ?? sqliteMod.DatabaseSync;

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

@@ -98,6 +98,18 @@ export declare function getUserSubagentsDir(): string;
 export declare function getSystemWorkflowsDir(): string;
 export declare function getUserWorkflowsDir(): string;
 export declare function getUserSecretsDir(): string;
+/**
+ * Path to the secrets usage read-model database (~/.agents/secrets/secrets.db).
+ * Read at CALL time so a test can redirect it to a temp file via
+ * AGENTS_SECRETS_DB without racing the module-load capture of USER_SECRETS_DIR —
+ * mirrors the AGENTS_EVENTS_PATH / AGENTS_DEVICES_DIR escape hatches. Holds only
+ * value-free usage telemetry (which bundle was created/imported/exported/viewed/
+ * accessed/unlocked, when, by whom), never a secret value. It is a derived index
+ * fed FROM the emitSecretAudit chokepoint alongside the append-only
+ * ~/.agents/events.jsonl audit log — the same way sessions.db indexes session
+ * metadata off the real session flow — not a second write path.
+ */
+export declare function getSecretsDbPath(): string;
 export declare function getUserPromptcutsPath(): string;
 /** Canonical home anchor (HOME env override or os.homedir()). */
 export declare function getHomeDir(): string;
@@ -109,6 +121,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');
@@ -296,6 +299,20 @@ export function getUserSubagentsDir() { return USER_SUBAGENTS_DIR; }
 export function getSystemWorkflowsDir() { return SYSTEM_WORKFLOWS_DIR; }
 export function getUserWorkflowsDir() { return USER_WORKFLOWS_DIR; }
 export function getUserSecretsDir() { return USER_SECRETS_DIR; }
+/**
+ * Path to the secrets usage read-model database (~/.agents/secrets/secrets.db).
+ * Read at CALL time so a test can redirect it to a temp file via
+ * AGENTS_SECRETS_DB without racing the module-load capture of USER_SECRETS_DIR —
+ * mirrors the AGENTS_EVENTS_PATH / AGENTS_DEVICES_DIR escape hatches. Holds only
+ * value-free usage telemetry (which bundle was created/imported/exported/viewed/
+ * accessed/unlocked, when, by whom), never a secret value. It is a derived index
+ * fed FROM the emitSecretAudit chokepoint alongside the append-only
+ * ~/.agents/events.jsonl audit log — the same way sessions.db indexes session
+ * metadata off the real session flow — not a second write path.
+ */
+export function getSecretsDbPath() {
+    return process.env.AGENTS_SECRETS_DB ?? path.join(USER_SECRETS_DIR, 'secrets.db');
+}
 export function getUserPromptcutsPath() { return USER_PROMPTCUTS_FILE; }
 // ─── User operational path getters ────────────────────────────────────────────
 //
@@ -311,6 +328,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)`;
+    }
+}