@phnx-labs/agents-cli 1.20.82 → 1.20.84

package/dist/commands/routines.js

@@ -13,7 +13,7 @@ import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, placementRequiresFiringPin, HOST_STRATEGIES, } from '../lib/routines.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -24,7 +24,7 @@ import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
-import { loadDevices } from '../lib/devices/registry.js';
+import { loadDevices, loadDevicesSync } from '../lib/devices/registry.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
 import { addHostOption } from '../lib/hosts/option.js';
 /**
@@ -75,6 +75,164 @@ function fireConditionLabel(job) {
     }
     return '-';
 }
+function scheduleLabel(job) {
+    let label = fireConditionLabel(job);
+    if (isOneShotRoutine(job))
+        label = `${label} (one-shot)`;
+    if (job.endAt) {
+        const end = new Date(job.endAt);
+        const endLabel = Number.isFinite(end.getTime())
+            ? end.toLocaleDateString()
+            : job.endAt;
+        label = `${label} (until ${endLabel})`;
+    }
+    return label;
+}
+function nextRunForDisplay(job, scheduler) {
+    if (isPastOneShotRoutine(job))
+        return null;
+    return scheduler.getNextRun(job.name);
+}
+function nextRunLabel(job, scheduler, now) {
+    if (isPastOneShotRoutine(job))
+        return 'expired';
+    return humanizeNextRun(scheduler.getNextRun(job.name) ?? null, now, job.timezone);
+}
+function deviceStateLabel(name, registry) {
+    const profile = registry[normalizeHost(name)] ?? registry[name];
+    if (!profile)
+        return 'unknown';
+    if (profile.reachability?.reachable === false)
+        return 'offline';
+    if (profile.reachability?.reachable === true)
+        return 'online';
+    if (profile.tailscale?.online === false)
+        return 'offline';
+    if (profile.tailscale?.online === true)
+        return 'online';
+    return 'unknown';
+}
+function titleWithDeviceState(title, name, registry) {
+    const state = deviceStateLabel(name, registry);
+    return state && state !== 'online' ? `${title} (${state})` : title;
+}
+function placementTag(job) {
+    const strategy = resolveHostStrategy(job);
+    if (strategy === 'local')
+        return job.host ? `->${job.host}` : '';
+    if (strategy === 'host')
+        return `->${job.host ?? '?'}`;
+    if (strategy === 'fleet')
+        return '->fleet';
+    return '->cloud';
+}
+function deviceLabel(job, width) {
+    const full = [job.devices?.join(',') ?? '', placementTag(job)]
+        .filter(Boolean)
+        .join(' ');
+    const raw = full.length === 0 ? 'all' : full;
+    const display = width && raw.length > width
+        ? raw.slice(0, width - 1) + '…'
+        : raw;
+    return { raw, display, dim: full.length === 0 || !jobRunsOnThisDevice(job) };
+}
+export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
+    const groups = new Map();
+    const add = (key, title, job) => {
+        const existing = groups.get(key);
+        if (existing) {
+            existing.jobs.push(job);
+            return;
+        }
+        groups.set(key, { key, title, jobs: [job] });
+    };
+    for (const job of jobs) {
+        const strategy = resolveHostStrategy(job);
+        if (strategy === 'cloud') {
+            add('cloud', 'Cloud', job);
+            continue;
+        }
+        if (strategy === 'fleet') {
+            add('fleet', 'Fleet-wide', job);
+            continue;
+        }
+        if (strategy === 'host') {
+            const host = job.host ?? 'unknown-host';
+            add(`host:${normalizeHost(host)}`, titleWithDeviceState(`Host: ${host}`, host, registry), job);
+            continue;
+        }
+        const devices = job.devices ?? [];
+        if (devices.length === 0) {
+            add('fleet', 'Fleet-wide', job);
+            continue;
+        }
+        for (const device of devices) {
+            const normalized = normalizeHost(device);
+            if (normalized === self) {
+                add('this-machine', `This machine (${self})`, job);
+            }
+            else {
+                add(`device:${normalized}`, titleWithDeviceState(`Device: ${normalized}`, normalized, registry), job);
+            }
+        }
+    }
+    const order = (group) => {
+        if (group.key === 'this-machine')
+            return 0;
+        if (group.key === 'fleet')
+            return 1;
+        if (group.key === 'cloud')
+            return 2;
+        if (group.key.startsWith('device:'))
+            return 3;
+        if (group.key.startsWith('host:'))
+            return 4;
+        return 5;
+    };
+    return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
+}
+function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
+    const NAME_W = 24;
+    const AGENT_W = 10;
+    const REPO_W = REPO_DISPLAY_MAX;
+    const DEVICE_W = 22;
+    const SCHED_W = 34;
+    const ENABLED_W = 10;
+    const NEXT_W = 22;
+    const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Devices'.padEnd(DEVICE_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
+    console.log(chalk.gray(header));
+    console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + DEVICE_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
+    for (const job of jobs) {
+        const nextStr = nextRunLabel(job, scheduler, now);
+        const schedStr = scheduleLabel(job);
+        const latestRun = getLatestRun(job.name);
+        const lastStatus = latestRun?.status || '-';
+        const sourceRepo = job.source?.repo ?? job.repo;
+        const sourceLabel = sourceRepo
+            ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
+            : null;
+        const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
+        const repoCell = link(repoInfo.display, repoInfo.href);
+        const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
+        const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
+        const enabledWord = job.enabled ? 'yes' : 'no';
+        const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
+        const device = deviceLabel(job, DEVICE_W);
+        const deviceCell = device.dim ? chalk.gray(device.display) : device.display;
+        const devicePad = Math.max(0, DEVICE_W - device.display.length);
+        const statusColor = lastStatus === 'completed' ? chalk.green
+            : lastStatus === 'failed' ? chalk.red
+                : lastStatus === 'timeout' ? chalk.yellow
+                    : chalk.gray;
+        const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
+        const agentLabelPadded = job.command
+            ? chalk.magenta('command'.padEnd(10))
+            : job.workflow
+                ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
+                : (job.agent || '').padEnd(10);
+        console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+    }
+}
 function parseRoutineTrigger(options) {
     const raw = typeof options.on === 'string' ? options.on : undefined;
     if (!raw)
@@ -308,7 +466,13 @@ export function registerRoutinesCommands(program) {
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
         .option('--json', 'Emit machine-readable JSON instead of the table (used by the menu bar helper)')
+        .option('--group-by <field>', 'Group table output by device (default for terminal output)')
+        .option('--flat', 'Print the legacy flat table instead of grouped sections')
         .action((options) => {
+        if (options.groupBy && options.groupBy !== 'device') {
+            console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: device`));
+            process.exit(1);
+        }
         try {
             monitorRunningJobs();
         }
@@ -339,7 +503,6 @@ export function registerRoutinesCommands(program) {
         if (options.json) {
             const nowJson = new Date();
             const payload = jobs.map((job) => {
-                const nextRun = scheduler.getNextRun(job.name);
                 const latestRun = getLatestRun(job.name);
                 return {
                     name: job.name,
@@ -357,11 +520,14 @@ export function registerRoutinesCommands(program) {
                     source: job.source ?? null,
                     sourceRepo: job.source?.repo ?? job.repo ?? null,
                     sourceBranch: job.source?.branch ?? null,
+                    runOnce: Boolean(job.runOnce),
+                    oneShot: isOneShotRoutine(job),
+                    expired: isPastOneShotRoutine(job, nowJson),
                     runsHere: jobRunsOnThisDevice(job),
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
-                    nextRun: nextRun ? nextRun.toISOString() : null,
-                    nextRunHuman: humanizeNextRun(nextRun ?? null, nowJson, job.timezone),
+                    nextRun: nextRunForDisplay(job, scheduler)?.toISOString() ?? null,
+                    nextRunHuman: nextRunLabel(job, scheduler, nowJson),
                     lastStatus: latestRun?.status ?? null,
                     exitCode: latestRun?.exitCode ?? null,
                     failureReason: latestRun?.errorMessage ?? null,
@@ -379,76 +545,21 @@ export function registerRoutinesCommands(program) {
         // contains raw ESC ] 8 ;; ... BEL escape sequences.
         const link = (label, url) => url && process.stdout.isTTY ? `\x1b]8;;${url}\x07${label}\x1b]8;;\x07` : label;
         const now = new Date();
-        const NAME_W = 24;
-        const AGENT_W = 10;
-        const REPO_W = REPO_DISPLAY_MAX;
-        const DEVICE_W = 22;
-        const SCHED_W = 22;
-        const ENABLED_W = 10;
-        const NEXT_W = 22;
-        const header = `  ${'Name'.padEnd(NAME_W)} ${'Agent'.padEnd(AGENT_W)} ${'Repo'.padEnd(REPO_W)} ${'Devices'.padEnd(DEVICE_W)} ${'Schedule'.padEnd(SCHED_W)} ${'Enabled'.padEnd(ENABLED_W)} ${'Next Run'.padEnd(NEXT_W)} Last Status`;
-        console.log(chalk.gray(header));
-        console.log(chalk.gray('  ' + '-'.repeat(NAME_W + AGENT_W + REPO_W + DEVICE_W + SCHED_W + ENABLED_W + NEXT_W + 20)));
-        for (const job of jobs) {
-            const nextRun = scheduler.getNextRun(job.name);
-            const nextStr = humanizeNextRun(nextRun ?? null, now, job.timezone);
-            let schedStr = fireConditionLabel(job);
-            if (job.endAt) {
-                const end = new Date(job.endAt);
-                const endLabel = Number.isFinite(end.getTime())
-                    ? end.toLocaleDateString()
-                    : job.endAt;
-                schedStr = `${schedStr} (until ${endLabel})`;
-            }
-            const latestRun = getLatestRun(job.name);
-            const lastStatus = latestRun?.status || '-';
-            // Prefer project-source repo (with optional @branch) over bare job.repo.
-            const sourceRepo = job.source?.repo ?? job.repo;
-            const sourceLabel = sourceRepo
-                ? (job.source?.branch ? `${sourceRepo}@${job.source.branch}` : sourceRepo)
-                : null;
-            const repoInfo = formatRepoLink(sourceLabel ?? job.repo);
-            const repoCell = link(repoInfo.display, repoInfo.href);
-            // Pad based on the display string, not the raw cell (which may include escape codes).
-            const repoPadding = Math.max(0, REPO_W - repoInfo.display.length);
-            const enabledStr = job.enabled ? chalk.green('yes') : chalk.gray('no');
-            // chalk adds escape codes; pad the raw word and let chalk wrap it.
-            const enabledWord = job.enabled ? 'yes' : 'no';
-            const enabledPad = Math.max(0, ENABLED_W - enabledWord.length);
-            // Placement rides in the Devices cell: eligibility →execution strategy.
-            const strategy = resolveHostStrategy(job);
-            const placementTag = strategy === 'local'
-                ? (job.host ? `→${job.host}` : '')
-                : strategy === 'host'
-                    ? `→${job.host ?? '?'}`
-                    : strategy === 'fleet'
-                        ? '→fleet'
-                        : '→cloud';
-            const deviceFull = [job.devices?.join(',') ?? '', placementTag]
-                .filter(Boolean)
-                .join(' ');
-            const deviceWord = deviceFull.length === 0
-                ? 'all'
-                : deviceFull.length > DEVICE_W
-                    ? deviceFull.slice(0, DEVICE_W - 1) + '…'
-                    : deviceFull;
-            const deviceCell = deviceFull.length === 0
-                ? chalk.gray('all')
-                : jobRunsOnThisDevice(job)
-                    ? deviceWord
-                    : chalk.gray(deviceWord);
-            const devicePad = Math.max(0, DEVICE_W - deviceWord.length);
-            const statusColor = lastStatus === 'completed' ? chalk.green
-                : lastStatus === 'failed' ? chalk.red
-                    : lastStatus === 'timeout' ? chalk.yellow
-                        : chalk.gray;
-            const overdueTag = overdueSet.has(job.name) ? chalk.yellow(' (overdue)') : '';
-            const agentLabelPadded = job.command
-                ? chalk.magenta('command'.padEnd(10))
-                : job.workflow
-                    ? chalk.magenta(`wf:${job.workflow}`.padEnd(10))
-                    : (job.agent || '').padEnd(10);
-            console.log(`  ${chalk.cyan(job.name.padEnd(NAME_W))} ${agentLabelPadded} ${repoCell}${' '.repeat(repoPadding)} ${deviceCell}${' '.repeat(devicePad)} ${schedStr.padEnd(SCHED_W)} ${enabledStr}${' '.repeat(enabledPad)} ${chalk.gray(nextStr.padEnd(NEXT_W))} ${statusColor(lastStatus)}${overdueTag}`);
+        if (options.flat) {
+            renderRoutineRows({ jobs, scheduler, overdueSet, link, now });
+        }
+        else {
+            let registry = {};
+            try {
+                registry = loadDevicesSync();
+            }
+            catch (err) {
+                console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
+            }
+            for (const group of groupRoutineJobsByDevice(jobs, registry)) {
+                console.log(chalk.bold(`\n${group.title}`));
+                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+            }
         }
         if (overdueSet.size > 0) {
             console.log();
@@ -520,6 +631,10 @@ export function registerRoutinesCommands(program) {
                 schedule = parsed.schedule;
                 runOnce = parsed.runOnce;
             }
+            if (!options.at && isOneShotLikeSchedule(schedule)) {
+                runOnce = true;
+                console.error(chalk.yellow(`Schedule "${schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
+            }
             if (!schedule && !trigger) {
                 console.error(chalk.red('Schedule or trigger is required (use --schedule, --at, or --on)'));
                 process.exit(1);
@@ -661,6 +776,10 @@ export function registerRoutinesCommands(program) {
                 enabled: true,
                 ...parsed,
             };
+            if (isOneShotLikeSchedule(config.schedule)) {
+                config.runOnce = true;
+                console.error(chalk.yellow(`Schedule "${config.schedule}" pins minute, hour, day, and month; treating it as one-shot. Prefer --at for one-time routines.`));
+            }
             // Same duplicate-fire guard as --placement/--run-on: off-box placement
             // with no eligibility pin would fire from every daemon in the fleet.
             const fileStrategy = resolveHostStrategy(config);
@@ -688,6 +807,41 @@ export function registerRoutinesCommands(program) {
             ensureSchedulerRunning();
         }
     });
+    routinesCmd
+        .command('cleanup')
+        .description('Remove expired one-shot routines that already fired and still have a user-layer YAML file.')
+        .option('--dry-run', 'Show routines that would be removed without deleting files')
+        .action((options) => {
+        const jobs = listAllJobs()
+            .filter((job) => getJobPath(job.name) !== null)
+            .filter((job) => hasCompletedOneShotRun(job));
+        if (jobs.length === 0) {
+            console.log(chalk.gray('No completed expired one-shot routines to clean up.'));
+            return;
+        }
+        if (options.dryRun) {
+            console.log(chalk.bold('Expired one-shot routines eligible for cleanup\n'));
+            for (const job of jobs) {
+                console.log(`  ${chalk.cyan(job.name)} ${chalk.gray(scheduleLabel(job))}`);
+            }
+            console.log(chalk.gray(`\nDry run. Remove with: agents routines cleanup`));
+            return;
+        }
+        let removed = 0;
+        for (const job of jobs) {
+            if (deleteJob(job.name)) {
+                removed++;
+                console.log(chalk.green(`Removed ${job.name}`));
+            }
+        }
+        console.log(chalk.gray(`Cleaned up ${removed} expired one-shot routine(s).`));
+        try {
+            signalDaemonReload();
+        }
+        catch {
+            // The daemon may not be running; the next start will read the cleaned directory.
+        }
+    });
     routinesCmd
         .command('remove [name]')
         .description('Delete a routine. Stops scheduling future runs; past execution logs remain on disk.')

package/dist/commands/sessions.d.ts

@@ -3,6 +3,66 @@ import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types
 import { type ActiveSession } from '../lib/session/active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type PickedSession } from './sessions-picker.js';
+interface SessionFilterOptions {
+    agent?: string;
+    project?: string;
+    all?: boolean;
+    teams?: boolean;
+    routine?: boolean;
+    since?: string;
+    until?: string;
+}
+interface SessionsOptions extends SessionFilterOptions {
+    /** Also list sessions from the user's own unmanaged ~/.<agent> installs. */
+    unmanaged?: boolean;
+    query?: string;
+    limit?: string;
+    sort?: string;
+    json?: boolean;
+    markdown?: boolean;
+    /** Commander populates this from `--no-redact`: true by default, false when the flag is passed. */
+    redact?: boolean;
+    include?: string;
+    exclude?: string;
+    first?: string;
+    last?: string;
+    artifacts?: boolean;
+    artifact?: string;
+    active?: boolean;
+    /** Emit the on-disk session-scan directories (requires --json); for watchers. */
+    roots?: boolean;
+    cloud?: boolean;
+    host?: string[];
+    /** Group the listing by directory and drop the id/version columns. */
+    tree?: boolean;
+    /** Force the plain flat table instead of the grouped default overview. */
+    flat?: boolean;
+    /** With --active: show only sessions waiting on user input; exit 1 if any. */
+    waiting?: boolean;
+    /** Enrich the listing with live glyphs/preview for running rows. Default on;
+     * `--no-live` sets this false. Commander's `--no-` convention. */
+    live?: boolean;
+    /** Force local-only: skip the cross-machine SSH fan-out (both the default
+     * listing and --active). */
+    local?: boolean;
+    /** --device <target...> — alias for --host; resolves against the device registry. */
+    device?: string[];
+    /** Per-agent shorthands: aliases for `--agent <name>` (prioritized harnesses). */
+    claude?: boolean;
+    codex?: boolean;
+    kimi?: boolean;
+    antigravity?: boolean;
+    grok?: boolean;
+    opencode?: boolean;
+    /** Force the printed listing even on a TTY. Commander's `--no-` convention:
+     * `--no-interactive` sets this false, opting out of the interactive browser. */
+    interactive?: boolean;
+    /** Print the canonical `ag sessions …` command for the given flags and exit —
+     * the non-interactive twin of the browser's `y` hotkey. */
+    printCmd?: boolean;
+    /** Print a compact preview of the matched session and exit (no pager). */
+    preview?: boolean;
+}
 /**
  * Strip terminal/harness noise from a preview so the column stays a single line
  * of plain prose: OSC title escapes, CSI/SGR ANSI, and the harness wrapper tags
@@ -10,6 +70,16 @@ import { type PickedSession } from './sessions-picker.js';
  * a captured transcript tail. Collapses runs of whitespace.
  */
 export declare function cleanPreview(text: string): string;
+/**
+ * Build the live description for an active session: checklist progress (when
+ * present) plus the state engine's preview (the latest turn), a user label, or
+ * the first-prompt topic. Used by both the flat listing's `doing` cell and as
+ * the snippet half of the --active row (identity is layered on in printActiveRow).
+ *
+ * Covers every ActiveSession context: terminal (interactive), headless, teams,
+ * cloud, and sub-agent rows that share the same ActiveSession.todos field.
+ */
+export declare function buildSessionDescription(s: ActiveSession): string;
 /**
  * Identity + checklist + live snippet for an --active / cross-machine row.
  * Surfaces agent-adjacent identity the flat table already has (label, project)
@@ -190,6 +260,20 @@ export declare function gatherActiveSessions(opts?: {
     sessions: ActiveSession[];
     remoteDeviceCount: number;
 }>;
+/**
+ * A bare interactive fleet listing — no query, no render/filter flag — that the
+ * `runSessionBrowser` picker can represent. The single predicate shared by the
+ * bare-browser branch and the `--host` early-return guard so they can't drift:
+ * when this holds, an explicit `--host`/`--device` scope is folded into the
+ * browser (preview-rich, selectable) instead of the legacy per-host raw stream.
+ */
+export declare function isBareBrowserListing(options: SessionsOptions, query: string | undefined): boolean;
+/**
+ * Pure flag-gate half of {@link isBareBrowserListing} (TTY-independent, so it is
+ * unit-testable): true when no query, render, or filter flag is present that the
+ * `runSessionBrowser` picker cannot represent.
+ */
+export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
 /** One flat table row:
  *   shortId · agent · version · model · project · [glyph] label·doing · [ticket] · [wt] · time
  * `doing` is the live preview when running, else the topic. The `ticket` column

package/dist/commands/sessions.js

@@ -240,22 +240,33 @@ export function cleanPreview(text) {
  * Covers every ActiveSession context: terminal (interactive), headless, teams,
  * cloud, and sub-agent rows that share the same ActiveSession.todos field.
  */
-function buildSessionDescription(s) {
+export function buildSessionDescription(s) {
     const todo = formatTodoCompact(s.todos);
     if (s.context === 'cloud') {
         const base = s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
         return cleanPreview([todo, base].filter(Boolean).join(' · '));
     }
     if (s.context === 'teams') {
+        // A teams row identifies its TEAM, then the teammate within it, then who
+        // spun it up, then what it's working on — so several teams from one
+        // orchestrator stay distinct and each shows its target, not just its slug.
         const parts = [s.teamName];
+        // Teammate name (distinct from the team slug) — which member this row is.
+        if (s.label && s.label !== s.teamName)
+            parts.push(s.label);
+        // Lineage: which orchestrator spun up this team. Prefer the resolved label,
+        // else the short session id, so "by whom" is answerable at a glance.
+        const orch = s.orchestratorLabel || (s.orchestratorSessionId ? s.orchestratorSessionId.slice(0, 8) : '');
+        if (orch)
+            parts.push(`by ${orch}`);
         if (todo)
             parts.push(todo);
-        if (s.preview)
-            parts.push(s.preview);
-        else if (s.label)
-            parts.push(s.label);
-        else if (s.topic)
-            parts.push(s.topic);
+        // Target: the live latest turn if working, else the assigned mission (the
+        // team's task/target, shown even before the teammate has a transcript), else
+        // the transcript topic.
+        const target = s.preview || s.assignedTask || s.topic;
+        if (target)
+            parts.push(target);
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.
@@ -997,6 +1008,33 @@ function printCrossMachineTip() {
 function useInteractiveBrowser(options) {
     return options.interactive !== false && !options.json && isInteractiveTerminal();
 }
+/**
+ * A bare interactive fleet listing — no query, no render/filter flag — that the
+ * `runSessionBrowser` picker can represent. The single predicate shared by the
+ * bare-browser branch and the `--host` early-return guard so they can't drift:
+ * when this holds, an explicit `--host`/`--device` scope is folded into the
+ * browser (preview-rich, selectable) instead of the legacy per-host raw stream.
+ */
+export function isBareBrowserListing(options, query) {
+    return useInteractiveBrowser(options) && hasNoBrowserDisqualifyingFlags(options, query);
+}
+/**
+ * Pure flag-gate half of {@link isBareBrowserListing} (TTY-independent, so it is
+ * unit-testable): true when no query, render, or filter flag is present that the
+ * `runSessionBrowser` picker cannot represent.
+ */
+export function hasNoBrowserDisqualifyingFlags(options, query) {
+    return (!query &&
+        !options.routine &&
+        !options.flat &&
+        !options.tree &&
+        !options.markdown &&
+        !options.until &&
+        !options.project &&
+        !options.sort &&
+        !options.artifacts &&
+        options.artifact === undefined);
+}
 /** The canonical `ag sessions …` command for a set of flags — the twin of the
  * browser's `y` hotkey (see --print-cmd). Normalizes to the stable flag form. */
 function canonicalSessionsCommand(query, options) {
@@ -1099,14 +1137,21 @@ async function sessionsAction(query, options) {
             await runRemoteSessionsJson(options.host);
             return;
         }
-        try {
-            runRemoteSessions(options.host);
-        }
-        catch (err) {
-            console.error(chalk.red(err.message));
-            process.exit(1);
+        // A bare interactive `--host`/`--device <box>` listing falls through to the
+        // fleet browser below, which folds the named host(s) into the same merged,
+        // preview-rich, selectable view as the local listing (via gatherRemoteList).
+        // A query, a render/filter flag, or a non-interactive caller keeps the legacy
+        // per-host raw stream under a `── host ──` banner.
+        if (!isBareBrowserListing(options, query)) {
+            try {
+                runRemoteSessions(options.host);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            return;
         }
-        return;
     }
     // --preview <id/query>: resolve one session and print its compact preview, then
     // exit — checked before --active so `--active --preview <id>` peeks the id
@@ -1160,17 +1205,7 @@ async function sessionsAction(query, options) {
     // filter the browser can't represent), or --no-interactive keep the existing
     // printed/render paths (agents and scripts unaffected). An explicit --since seeds
     // the browser's window so the flag is honored, not swallowed.
-    if (useInteractiveBrowser(options) &&
-        !query &&
-        !options.routine &&
-        !options.flat &&
-        !options.tree &&
-        !options.markdown &&
-        !options.until &&
-        !options.project &&
-        !options.sort &&
-        !options.artifacts &&
-        options.artifact === undefined) {
+    if (isBareBrowserListing(options, query)) {
         const { runSessionBrowser, bareBrowserSeed } = await import('./sessions-browser.js');
         await runSessionBrowser(bareBrowserSeed({
             teams: options.teams,