@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/commands/activity.js

@@ -1,13 +1,37 @@
 import chalk from 'chalk';
-import { collapseActivity, enrichActivityEvents, ensureActivityLogHook, filterActivityEvents, formatActivityGroupHeader, formatEnrichedActivityLine, formatProgressUpdate, groupActivity, mergeActivityEvents, parseActivityPayload, projectFromCwd, readRecentActivity, styleForEvent, tierForEvent, } from '../lib/activity.js';
+import { ACTIVITY_HOOK_DEFINITIONS, collapseActivity, enrichActivityEvents, capActivityEvents, ensureActivityLogHook, filterActivityByProject, filterActivityEvents, formatActivityGroupMeta, formatEnrichedActivityLine, formatProgressUpdate, groupActivity, mergeActivityEvents, parseActivityPayload, readRecentActivity, styleForEvent, tierForEvent, } from '../lib/activity.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
+import { resolveProjectKey } from '../lib/project-key.js';
+import { listProjectDefs, projectNameForCwd, resolveProjectNameForCwd } from '../lib/projects.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { shouldIncludeLocalFeed, remoteFeedHostsToDial } from './feed.js';
 import { getActiveSessions } from '../lib/session/active.js';
 /** Recursion guard: a peer answering a fan-out never re-fans-out itself. */
 export const ACTIVITY_NO_FANOUT_ENV = 'AGENTS_ACTIVITY_LOCAL';
+/** `--group-by` values; `none` is the opt-out that `--flat` also selects. */
 const GROUP_BY_VALUES = ['project', 'device', 'agent'];
-/** Wire the activity-log hooks into each hooks-capable version's settings. */
+const GROUP_BY_NONE = 'none';
+/** Grouping when neither `--group-by` nor `--flat` is given. */
+const DEFAULT_GROUP_BY = 'project';
+/**
+ * How much further back than `--limit` the LOCAL log read goes, so routine
+ * churn on this box can't crowd the fleet's milestones out of the window
+ * ({@link capActivityEvents} does the real capping).
+ */
+const LOCAL_READ_HEADROOM = 5;
+/**
+ * Wire the activity-log hooks into each hooks-capable version's settings.
+ *
+ * Only a failure that leaves THIS command's log unwritten is worth a warning.
+ * `registerHooksToSettings` reports every unresolved hook in the manifest — a
+ * missing `inject-session-id` script, someone else's half-installed plugin —
+ * and echoing all of them printed five wrapped lines of unrelated noise above
+ * the timeline on every run. Those belong to `agents doctor`, which exists to
+ * find them; here they are dropped. What still surfaces: an activity-hook
+ * failure, and any error attributable to NO manifest hook — a corrupt
+ * settings.json or an unwritable hooks file aborts registration for the whole
+ * agent, which is exactly a failure that leaves the activity log unwritten.
+ */
 async function installActivityHooks() {
     const warnings = [];
     const hookInstall = ensureActivityLogHook();
@@ -20,22 +44,45 @@ async function installActivityHooks() {
         import('../lib/versions.js'),
     ]);
     const manifest = parseHookManifest({ warn: false });
+    const manifestNames = Object.keys(manifest);
     for (const { agent, version } of iterHooksCapableVersions({ agent: 'claude' })) {
         const result = registerHooksToSettings(agent, getVersionHomePath(agent, version), manifest);
-        if (result.errors.length > 0)
-            warnings.push(`${agent}@${version}: ${result.errors.join('; ')}`);
+        const ours = result.errors.filter((e) => isActivityHookError(e) || !isManifestHookError(e, manifestNames));
+        if (ours.length > 0)
+            warnings.push(`${agent}@${version}: ${ours.join('; ')}`);
     }
     return warnings;
 }
-/** Session facts (project / ticket / execution host) keyed for the read-time join. */
-function activityHintsFromSessions(sessions) {
+/**
+ * Does this hook-registration error concern one of the activity-log hooks?
+ * `registerHooksToSettings` prefixes each error with the manifest hook name
+ * (`<name>: script not found`), so the entry names are the discriminator.
+ */
+export function isActivityHookError(error) {
+    return Object.keys(ACTIVITY_HOOK_DEFINITIONS).some((name) => error.startsWith(`${name}:`));
+}
+/**
+ * Is this error attributable to a named manifest hook at all? Errors that name
+ * no hook — `Failed to parse settings.json`, `Failed to write
+ * agents-cli-hooks.ts: …` — are agent-level aborts, not per-hook noise, and
+ * must never be filtered out.
+ */
+export function isManifestHookError(error, manifestNames) {
+    return manifestNames.some((name) => error.startsWith(`${name}:`));
+}
+/**
+ * Session facts (project / ticket / execution host) keyed for the read-time
+ * join. These sessions are this machine's, so their cwds get the canonical
+ * defined-project-first resolution rather than the bare cwd fold.
+ */
+function activityHintsFromSessions(sessions, resolveProject = resolveProjectKey) {
     return sessions.map((s) => ({
         sessionId: s.sessionId,
         ticket: s.ticket?.id,
         // Where the process actually lives — the SSH-resolved provenance host, else
         // the cross-machine `machine` id. Normalized to match the event `host` form.
         executionHost: s.provenance?.host ? normalizeHost(s.provenance.host) : s.machine,
-        project: projectFromCwd(s.cwd),
+        project: resolveProject(s.cwd),
     }));
 }
 /**
@@ -70,6 +117,23 @@ function renderFlat(events, opts) {
     }
     process.stdout.write('\n');
 }
+/** Max peers named in the unreachable note before the rest collapse to `+N`. */
+const UNREACHABLE_NAME_LIMIT = 4;
+/**
+ * One compact trailing note for peers that didn't answer the fan-out. Now that
+ * every run dials the fleet, an offline box is routine -- but never silent: the
+ * reader has to know the timeline is missing a machine, not that the machine
+ * was idle. Empty string when everything answered.
+ */
+export function formatUnreachableNote(skipped) {
+    if (skipped.length === 0)
+        return '';
+    const named = skipped.slice(0, UNREACHABLE_NAME_LIMIT);
+    const rest = skipped.length - named.length;
+    const list = rest > 0 ? `${named.join(', ')} +${rest}` : named.join(', ');
+    const noun = skipped.length === 1 ? 'device' : 'devices';
+    return chalk.gray(`  · ${skipped.length} ${noun} unreachable: ${list}\n\n`);
+}
 /** Print the bucketed view (`--group-by project|device|agent`). */
 function renderGrouped(events, by, opts) {
     const groups = groupActivity(events, by);
@@ -78,7 +142,11 @@ function renderGrouped(events, by, opts) {
     const showProject = by !== 'project';
     process.stdout.write(chalk.bold(`\n  activity by ${by}\n`));
     for (const group of groups) {
-        process.stdout.write(`\n  ${chalk.bold(formatActivityGroupHeader(group))}\n`);
+        // `▸ <label>  <meta>` -- label leads in cyan so projects scan down the
+        // left edge (mirrors the `agents sessions` overview), the counts and the
+        // machines that touched this project trail behind it in gray.
+        const meta = formatActivityGroupMeta(group, { showDevices: by !== 'device' });
+        process.stdout.write(`\n  ${chalk.cyan('▸')} ${chalk.cyan.bold(group.label)}  ${chalk.gray(meta)}\n`);
         const { milestones, counts, subagentCount } = collapseActivity(group.events);
         const shown = opts.all ? group.events : milestones;
         for (const ev of shown) {
@@ -97,89 +165,168 @@ function renderGrouped(events, by, opts) {
     }
     process.stdout.write('\n');
 }
+/**
+ * Resolve `--group-by` / `--flat` into the grouping dimension, or `undefined`
+ * for a flat stream. Throws on an unknown value so the caller can exit 1 --
+ * a mistyped dimension must not silently fall back to the default.
+ */
+export function resolveActivityGrouping(opts) {
+    if (opts.flat)
+        return undefined;
+    if (opts.groupBy === undefined)
+        return DEFAULT_GROUP_BY;
+    if (opts.groupBy === GROUP_BY_NONE)
+        return undefined;
+    if (!GROUP_BY_VALUES.includes(opts.groupBy)) {
+        throw new Error(`--group-by must be one of: ${[...GROUP_BY_VALUES, GROUP_BY_NONE].join(', ')}`);
+    }
+    return opts.groupBy;
+}
+/**
+ * Decide the read scope. Fleet-wide is the DEFAULT -- agents run on every box,
+ * so "what are my agents doing" is a fleet question -- and three things narrow
+ * it: `--local`, an explicit `--host`/`--device` list, and the recursion guard
+ * a peer answering a fan-out carries (else every peer would re-fan the fleet).
+ * `--devices-all`/`--hosts-all` are kept as explicit no-ops for scripts that
+ * already pass them.
+ */
+export function resolveActivityScope(opts, self, noFanoutEnv = process.env[ACTIVITY_NO_FANOUT_ENV] === '1') {
+    if (opts.local === true || noFanoutEnv)
+        return { includeLocal: true, wantRemote: false };
+    const explicitHosts = opts.host;
+    if (explicitHosts && explicitHosts.length > 0) {
+        const remoteHosts = remoteFeedHostsToDial(explicitHosts, self) ?? [];
+        return {
+            includeLocal: shouldIncludeLocalFeed(explicitHosts, self),
+            wantRemote: remoteHosts.length > 0,
+            remoteHosts,
+        };
+    }
+    return { includeLocal: true, wantRemote: true };
+}
 export function registerActivityCommand(program) {
     program
         .command('activity')
-        .description('Recent agent activity -- plans, PRs, worktrees, sub-agents (newest first)')
+        .description('Recent agent activity across the fleet -- plans, PRs, worktrees, sub-agents, by project')
         .option('--json', 'Emit the (enriched) event list as JSON')
         .option('--all', 'Include routine activity (file edits) inline, not collapsed')
         .option('--milestones', 'Only milestone events (plans, PRs, worktrees, sub-agents)')
-        .option('-n, --limit <n>', 'Cap the number of events shown', (v) => parseInt(v, 10), 40)
+        .option('-n, --limit <n>', 'Cap the milestones shown (routine work rides along as counts); with --all, caps every event', (v) => parseInt(v, 10), 40)
         .option('--since <minutes>', 'Only events within the last N minutes', (v) => parseInt(v, 10))
         .option('--local', 'Only this machine -- skip the cross-machine SSH fan-out')
         .option('-H, --host <target...>', 'Scope to remote machine(s) over SSH; repeatable')
         .option('--device <target...>', 'Alias for --host; repeatable')
-        .option('--devices-all', 'Fan out to every reachable device on the fleet')
+        .option('--devices-all', 'Fan out to every reachable device (the default; kept for scripts)')
         .option('--hosts-all', 'Alias for --devices-all')
-        .option('--group-by <field>', 'Bucket the stream by project | device | agent')
+        .option('--group-by <field>', 'Bucket the stream by project | device | agent | none (default: project)')
+        .option('--flat', 'One newest-first stream instead of project buckets')
+        .option('--project <name>', 'Only items under one project; exact match on the resolved (defined-project-first) label')
         .option('--filter <text>', 'Narrow to items matching a project / device / agent / event / ticket')
         .addHelpText('after', `
 Examples:
-  agents activity                              # this machine, newest first
-  agents activity --devices-all --group-by project   # per project across the fleet
+  agents activity                              # the whole fleet, by project
+  agents activity --local                      # just this machine
+  agents activity --flat                       # one newest-first stream
   agents activity --host yosemite-s1           # one box over SSH
-  agents activity --devices-all --filter RUSH-2100   # one ticket, fleet-wide
-  agents activity --milestones                 # only plans / PRs / worktrees / sub-agents
+  agents activity --project rush               # one defined project, fleet-wide
+  agents activity --filter RUSH-2100           # one ticket, fleet-wide
+  agents activity --group-by device            # by machine instead of project
 
-Each item is enriched by JOINING to live sessions (project, execution host,
-Linear ticket) -- never by re-parsing transcripts. --devices-all runs the same
-'activity --json' on each peer and merges the streams host-tagged.
+Fleet-wide and project-grouped by default: the same 'activity --json' runs on
+every reachable peer and the streams merge host-tagged. Each item is enriched by
+JOINING to live sessions (project, execution host, Linear ticket) -- never by
+re-parsing transcripts. Project labels are canonical: a cwd inside a defined
+project (~/.agents/projects/<name>.yaml) reads as that project's name, so a
+multi-repo project is one bucket; anything else folds to its repository. Each
+project header names the machines its work ran on.
 `)
         .action(async (opts) => {
         if (opts.device?.length)
             opts.host = [...(opts.host ?? []), ...opts.device];
-        const groupBy = opts.groupBy;
-        if (groupBy && !GROUP_BY_VALUES.includes(groupBy)) {
-            process.stderr.write(chalk.red(`--group-by must be one of: ${GROUP_BY_VALUES.join(', ')}\n`));
+        let groupBy;
+        try {
+            groupBy = resolveActivityGrouping(opts);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`${err.message}\n`));
             process.exitCode = 1;
             return;
         }
-        const self = machineId();
-        const forceLocal = opts.local === true || process.env[ACTIVITY_NO_FANOUT_ENV] === '1';
-        const explicitHosts = opts.host;
-        const wantAll = Boolean(opts.devicesAll || opts.hostsAll);
-        const wantRemote = !forceLocal && (wantAll || (explicitHosts != null && explicitHosts.length > 0));
-        // Local events are included unless an explicit --host list excludes this box.
-        let includeLocal = true;
-        if (wantRemote && explicitHosts && explicitHosts.length > 0) {
-            includeLocal = shouldIncludeLocalFeed(explicitHosts, self);
+        // `parseInt` yields NaN for a non-numeric -n, and every downstream slice
+        // against NaN is empty — an unreadable flag would otherwise render as
+        // "No recent agent activity", which is a lie about the fleet.
+        if (!Number.isFinite(opts.limit) || opts.limit <= 0) {
+            process.stderr.write(chalk.red('--limit must be a positive number\n'));
+            process.exitCode = 1;
+            return;
         }
+        const self = machineId();
+        const { includeLocal, wantRemote, remoteHosts } = resolveActivityScope(opts, self);
         const warnings = includeLocal ? await installActivityHooks() : [];
         const sinceMs = typeof opts.since === 'number' && opts.since > 0
             ? Date.now() - opts.since * 60_000
             : undefined;
+        // Each peer contributes its own newest `-n` window, so the merged pool is
+        // already several times the cap. The local read is the one source that
+        // would otherwise be capped twice, and reading further back costs nothing
+        // (the files are tailed either way) — so it gets the headroom.
         let events = includeLocal
-            ? readRecentActivity({ sinceMs, limit: opts.limit })
+            ? readRecentActivity({ sinceMs, limit: opts.limit * LOCAL_READ_HEADROOM })
             : [];
+        // Peers that were dialed but never answered, reported once at the end
+        // rather than as a line each above the timeline.
+        let unreachable = [];
         if (wantRemote) {
-            // Explicit hosts drop self (it's the local read); --devices-all dials
-            // every online peer (hosts undefined).
-            const remoteHosts = explicitHosts?.length ? remoteFeedHostsToDial(explicitHosts, self) : undefined;
-            if (!explicitHosts?.length || (remoteHosts && remoteHosts.length > 0)) {
-                const remoteArgs = ['activity', '--json', '-n', String(opts.limit)];
-                if (typeof opts.since === 'number' && opts.since > 0)
-                    remoteArgs.push('--since', String(opts.since));
-                const remote = await gatherRemoteAgentsJson({
-                    args: remoteArgs,
-                    noFanoutEnv: ACTIVITY_NO_FANOUT_ENV,
-                    hosts: remoteHosts,
-                    parse: parseActivityPayload,
-                });
-                events = mergeActivityEvents(events, remote.items);
-            }
+            const remoteArgs = ['activity', '--json', '-n', String(opts.limit)];
+            if (typeof opts.since === 'number' && opts.since > 0)
+                remoteArgs.push('--since', String(opts.since));
+            const remote = await gatherRemoteAgentsJson({
+                args: remoteArgs,
+                noFanoutEnv: ACTIVITY_NO_FANOUT_ENV,
+                hosts: remoteHosts?.length ? remoteHosts : undefined,
+                parse: parseActivityPayload,
+                quiet: true,
+            });
+            events = mergeActivityEvents(events, remote.items);
+            unreachable = remote.skipped;
         }
         // Enrich by joining to live LOCAL sessions (ticket/project/execution host).
         // Remote events arrive already enriched by their own peer, so the join only
         // fills local ones; the pure fallbacks (cwd->project, host->device) cover
         // everything either way. Skip the ps/lsof scan when there's nothing to show.
+        // Project labels are canonical: a defined project's name wins over the
+        // repo-level key — including over a stale or def-skewed pre-baked stamp
+        // (the def match is a pure prefix compare; foreign paths just don't match),
+        // so a multi-repo project buckets as one even across version skew.
+        const projectDefs = listProjectDefs();
+        const canonicalProject = (cwd) => projectNameForCwd(cwd ?? undefined, projectDefs);
+        const resolveProject = (cwd) => resolveProjectNameForCwd(cwd, projectDefs);
         const sessions = includeLocal && events.length > 0 ? await getActiveSessions() : [];
-        let enriched = enrichActivityEvents(events, activityHintsFromSessions(sessions));
+        let enriched = enrichActivityEvents(events, activityHintsFromSessions(sessions, resolveProject), resolveProject, canonicalProject);
         if (opts.milestones)
             enriched = enriched.filter((e) => tierForEvent(e.event) === 'milestone');
+        if (opts.project) {
+            const unfiltered = enriched;
+            enriched = filterActivityByProject(enriched, opts.project);
+            // An exact-name flag that matches nothing deserves a useful answer, not
+            // a generic "no activity" that lies about the fleet.
+            if (enriched.length === 0 && unfiltered.length > 0) {
+                const seen = [...new Set(unfiltered.map((e) => e.project).filter((p) => !!p))].sort();
+                const defined = projectDefs.map((d) => d.name);
+                const parts = [
+                    seen.length ? `seen: ${seen.join(', ')}` : '',
+                    defined.length ? `defined: ${defined.join(', ')}` : '',
+                ].filter(Boolean);
+                process.stderr.write(chalk.gray(`  · no events for project "${opts.project}" (exact match)${parts.length ? ` — ${parts.join(' · ')}` : ''}\n`));
+            }
+        }
         if (opts.filter)
             enriched = filterActivityEvents(enriched, opts.filter);
-        enriched = enriched.slice(0, opts.limit);
+        enriched = capActivityEvents(enriched, opts.limit, { all: opts.all || opts.milestones });
         if (opts.json) {
+            // stdout stays clean JSON, but an unanswered peer is never a silent drop.
+            if (unreachable.length > 0)
+                process.stderr.write(formatUnreachableNote(unreachable));
             process.stdout.write(`${JSON.stringify(enriched, null, 2)}\n`);
             return;
         }
@@ -187,11 +334,13 @@ Linear ticket) -- never by re-parsing transcripts. --devices-all runs the same
             process.stderr.write(chalk.yellow(`  ! ${w}\n`));
         if (enriched.length === 0) {
             process.stdout.write(chalk.gray('No recent agent activity. Events appear here as agents create plans, open PRs, and spawn sub-agents.\n'));
+            process.stdout.write(formatUnreachableNote(unreachable));
             return;
         }
         if (groupBy)
             renderGrouped(enriched, groupBy, opts);
         else
             renderFlat(enriched, opts);
+        process.stdout.write(formatUnreachableNote(unreachable));
     });
 }

package/dist/commands/beta.js

@@ -4,6 +4,7 @@ const BETA_DESCRIPTIONS = {
     drive: 'Google Drive integration for reading and writing files',
     factory: 'Cloud-based agent dispatch via Rush Factory',
     'session-sync': 'Cross-machine session transcript sync via R2 (daemon push/pull)',
+    projects: 'Named multi-repo projects with a progress rollup (agents projects)',
 };
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);

package/dist/commands/doctor.js

@@ -12,7 +12,7 @@ import { getCliVersion } from '../lib/version.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
-import { machineId } from '../lib/session/sync/config.js';
+import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
@@ -101,7 +101,9 @@ async function resolveFleetTargets(opts) {
     const registry = await loadDevices();
     const localName = machineId();
     return Object.values(registry)
-        .filter((d) => d.name.toLowerCase() !== localName)
+        // Normalize names so zion/ZION/zion.local all match machineId() and we never
+        // self-SSH the local box during fleet probes (RUSH-2114).
+        .filter((d) => normalizeHost(d.name) !== localName)
         // Control devices (a cockpit) never run agents — skip them in the fleet
         // fan-out (an explicit --device <name> still resolves above).
         .filter((d) => !isControlDevice(d))

package/dist/commands/exec.d.ts

@@ -16,6 +16,20 @@ export interface RunAccountPickerRequest {
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export declare function parseRunAccountPickerRequest(agentSpec: string): RunAccountPickerRequest;
 /** Return every option whose routing semantics conflict with a local account choice. */
+/**
+ * The `--host` alias family — the flags that mean "dispatch this run to another
+ * machine over SSH". `--host` is canonical; `--device`/`--on`/`--computer` are
+ * aliases. Returns the values actually given (so callers can both test presence
+ * and read the target). Kept in ONE place because a guard that listed only a
+ * subset silently let `--terminal --device` open a local tab and drop the remote
+ * target — the drift this predicate exists to prevent.
+ */
+export declare function hostTargetGiven(options: {
+    host?: string;
+    device?: string;
+    on?: string;
+    computer?: string;
+}): string[];
 export declare function runAccountPickerConflicts(options: {
     resume?: string | boolean;
     strategy?: string;

package/dist/commands/exec.js

@@ -34,6 +34,17 @@ export function parseRunAccountPickerRequest(agentSpec) {
     };
 }
 /** Return every option whose routing semantics conflict with a local account choice. */
+/**
+ * The `--host` alias family — the flags that mean "dispatch this run to another
+ * machine over SSH". `--host` is canonical; `--device`/`--on`/`--computer` are
+ * aliases. Returns the values actually given (so callers can both test presence
+ * and read the target). Kept in ONE place because a guard that listed only a
+ * subset silently let `--terminal --device` open a local tab and drop the remote
+ * target — the drift this predicate exists to prevent.
+ */
+export function hostTargetGiven(options) {
+    return [options.host, options.device, options.on, options.computer].filter((v) => !!v);
+}
 export function runAccountPickerConflicts(options) {
     const conflicts = [];
     if (options.resume !== undefined)
@@ -46,7 +57,7 @@ export function runAccountPickerConflicts(options) {
         conflicts.push('--lease');
     if (options.box)
         conflicts.push('--box');
-    if (options.host || options.device || options.on || options.computer)
+    if (hostTargetGiven(options).length)
         conflicts.push('--host/--device');
     return conflicts;
 }
@@ -349,6 +360,121 @@ export async function runWorkflowForEach(spec, opts) {
     process.stderr.write(chalk.yellow(`[for_each] stopped by ${result.stoppedBy} after ${result.waves} waves. Team: ${team}\n`));
     return 1;
 }
+/**
+ * The run's working directory from `--cwd` / `--project`. `--project <slug>` owns
+ * the directory and is mutually exclusive with `--cwd`/`--remote-cwd`; both the
+ * main dispatch and the `--terminal` handoff need the same answer, so the rule
+ * and its error live here once instead of in two places that can drift.
+ */
+async function resolveRunCwd(options, opts) {
+    if (!options.project)
+        return options.cwd;
+    if (options.cwd || options.remoteCwd) {
+        console.error(chalk.red('Pass --project alone — not with --cwd or --remote-cwd.'));
+        process.exit(1);
+    }
+    const { resolveProjectRef } = await import('../lib/project-root.js');
+    try {
+        return await resolveProjectRef(options.project, { forRemote: opts.forRemote });
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+}
+/**
+ * `--terminal`: hand this run to a real terminal tab and exit.
+ *
+ * The terminal is detected from the user's live sessions, so a run started from
+ * a surface that cannot host a TUI (the menu bar's "New Session", a script) lands
+ * in the terminal they actually work in instead of a hardcoded Terminal.app.
+ * Exits non-zero when no terminal could be opened — the caller must not believe
+ * a session started when none did.
+ */
+async function handleTerminalHandoff(agentSpec, options, prompt) {
+    const { parseTerminalFlag, openRunInTerminal, toHostSamples } = await import('../lib/terminal/run-surface.js');
+    const { currentContext } = await import('../lib/terminal/index.js');
+    const parsed = parseTerminalFlag(options.terminal);
+    if (parsed.error) {
+        console.error(chalk.red(parsed.error));
+        process.exit(1);
+    }
+    // Reject an unrunnable target HERE, where the person can read it. The tab would
+    // otherwise open, print the same error, and close — the failure lands in a
+    // window that is gone before it can be read, which reads as "nothing happened".
+    //
+    // `agents run <thing>` takes an agent id, a PROFILE, or a WORKFLOW (see the
+    // isValidAgent / profileExists / resolveWorkflowRef chain below), so this must
+    // accept all three. Gating on the agent table alone rejected every profile —
+    // the whole Kimi/DeepSeek/Qwen/GLM path — for `--terminal` runs only.
+    const rawTarget = parseRunAccountPickerRequest(agentSpec).normalizedAgentSpec.split('@')[0];
+    const knownAgent = resolveAgentName(rawTarget);
+    if (knownAgent && isAgentHardDeprecated(knownAgent)) {
+        console.error(chalk.red(hardDeprecationError(knownAgent)));
+        process.exit(1);
+    }
+    if (!knownAgent) {
+        const [{ profileExists }, { resolveWorkflowRef }] = await Promise.all([
+            import('../lib/profiles.js'),
+            import('../lib/workflows.js'),
+        ]);
+        const probeCwd = options.cwd ?? process.cwd();
+        if (!profileExists(rawTarget) && !resolveWorkflowRef(rawTarget, probeCwd)) {
+            console.error(chalk.red(`Unknown agent, profile, or workflow: ${rawTarget}. See \`agents list\` for the installed harnesses.`));
+            process.exit(1);
+        }
+    }
+    // --host and its aliases (--device/--on/--computer) all mean "dispatch this
+    // run to another machine over SSH", which is incompatible with opening a
+    // terminal tab on THIS machine — so reject the whole alias family, not just
+    // the canonical flag. The rule and its wording live once, in the --host
+    // forwarding table, so the classification a reviewer reads and the error a
+    // user sees can't drift.
+    if (hostTargetGiven(options).length) {
+        const { RUN_OPTION_REJECT_MESSAGES } = await import('../lib/hosts/remote-cmd.js');
+        console.error(chalk.red(RUN_OPTION_REJECT_MESSAGES.terminal));
+        process.exit(1);
+    }
+    // Machine-readable output would land in the tab, where the caller that asked
+    // for it can never read it. Same class of failure as --host: refuse, don't
+    // hand back a stream that goes nowhere.
+    const streamFlag = options.json ? '--json' : options.emitSessionId ? '--emit-session-id' : undefined;
+    if (streamFlag) {
+        console.error(chalk.red(`${streamFlag} streams to stdout, but --terminal moves the run into a tab where you cannot read it. Drop one.`));
+        process.exit(1);
+    }
+    // `--project` owns the working directory, but the main action resolves it far
+    // below this handoff — so without this the tab would open in THIS process's
+    // cwd (launchd's `/` for a menu-bar click) while the run inside it moved to
+    // the project. `forRemote: false` because --terminal is always local (--host
+    // is rejected above).
+    const cwd = await resolveRunCwd(options, { forRemote: false });
+    const { getActiveSessions } = await import('../lib/session/active.js');
+    let sessions = [];
+    try {
+        sessions = await toHostSamples(await getActiveSessions());
+    }
+    catch {
+        // Detection is best-effort — an unreadable session index must not block the
+        // launch; resolution falls through to the available-backend floor.
+    }
+    const result = await openRunInTerminal({
+        argv: process.argv.slice(2),
+        forced: parsed.backend,
+        consumedValue: typeof options.terminal === 'string' ? options.terminal : undefined,
+        cwd: cwd ?? process.cwd(),
+        sessions,
+        ctx: currentContext(),
+    });
+    if (!result.ok) {
+        console.error(chalk.red(`Could not open a terminal: ${result.error ?? 'unknown error'}`));
+        process.exit(1);
+    }
+    if (!options.quiet) {
+        const what = prompt === undefined ? 'session' : 'run';
+        console.log(chalk.gray(`Opened the ${what} in ${result.description}.`));
+    }
+}
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
     const runCmd = program
@@ -374,6 +500,7 @@ export function registerRunCommand(program) {
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
+        .option('--terminal [backend]', "Open this run in a real terminal tab instead of here. Without a value the terminal is detected from your live sessions (`agents sessions --active` host), so it lands where you already work — Ghostty for a Ghostty user, iTerm for an iTerm user. Name one to force it: iterm | ghostty | terminal | tmux | vscodium-agent. This is how the menu bar's New Session opens.")
         .option('--verbose', 'Show detailed execution logs')
         .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--no-tmux', 'Spawn the agent directly instead of wrapping it in the shared tmux session. Same effect as --raw / AGENTS_NO_TMUX=1. Use this to see the agent\'s full startup output when a launch is failing.')
@@ -433,6 +560,11 @@ export function registerRunCommand(program) {
       # Pick a signed-in account/version for only this run
       agents run claude@
 
+      # Open the session in a terminal tab — detected from where your sessions
+      # already run (Ghostty / iTerm / Terminal.app); force one with a value
+      agents run claude --terminal
+      agents run claude --terminal ghostty
+
       # Pipe JSON events to a parser (--quiet drops the preamble)
       agents run claude "..." --json --quiet | jq
 
@@ -499,6 +631,15 @@ export function registerRunCommand(program) {
             // a native flag, not a prompt. Run interactively.
             prompt = undefined;
         }
+        // --terminal: this process can't host the TUI (a menu-bar click, a script),
+        // so hand the run to a real terminal and exit. Resolved from the user's own
+        // live sessions, so it opens where they already work. Done before every
+        // other dispatch path because the tab re-runs this same argv without the
+        // flag — arming --notify or picking a version here would happen twice.
+        if (options.terminal) {
+            await handleTerminalHandoff(agentSpec, options, prompt);
+            return;
+        }
         // --notify: post a desktop notification when this run finishes. Armed on
         // process exit so it covers EVERY dispatch path below (local, --host,
         // --lease, the error path) instead of one branch. Only for headless runs
@@ -906,24 +1047,13 @@ export function registerRunCommand(program) {
         }
         // --host/--on/--computer: offload this run onto a registered agent host
         // over SSH instead of running locally. The three flags are aliases.
-        const hostGiven = [options.host, options.device, options.on, options.computer].filter((v) => !!v);
+        const hostGiven = hostTargetGiven(options);
         // --project <slug>[@worktree]: resolve the projects-root shorthand into a
         // cwd. On a host run it resolves home-relative (`~/…`, so the host expands
         // it); locally it becomes an absolute path. It owns the working directory,
         // so it is mutually exclusive with both --cwd and --remote-cwd.
         if (options.project) {
-            if (options.cwd || options.remoteCwd) {
-                console.error(chalk.red('Pass --project alone — not with --cwd or --remote-cwd.'));
-                process.exit(1);
-            }
-            const { resolveProjectRef } = await import('../lib/project-root.js');
-            try {
-                options.cwd = await resolveProjectRef(options.project, { forRemote: hostGiven.length > 0 });
-            }
-            catch (err) {
-                console.error(chalk.red(err.message));
-                process.exit(1);
-            }
+            options.cwd = await resolveRunCwd(options, { forRemote: hostGiven.length > 0 });
         }
         if (hostGiven.length > 0) {
             if (new Set(hostGiven).size > 1) {