@phnx-labs/agents-cli 1.20.29 → 1.20.30

package/dist/commands/computer-actions.js

@@ -170,11 +170,15 @@ function emit(result, json, human) {
         console.log(human());
     }
 }
-// Add the shared --pid/--bundle target options to a verb.
+// Add the shared --pid/--bundle/--host target options to a verb. `--host` routes
+// the verb at a remote Windows device: the `computer` preAction hook hydrates
+// COMPUTER_HELPER_TCP from the tunnel `start --host` recorded, so withClient's
+// openComputerClient() transparently selects the TCP transport.
 function addTargetOpts(cmd) {
     return cmd
         .option('--bundle <id>', 'Bundle id of the target app (default: frontmost allow-listed app)')
-        .option('--pid <n>', 'Target pid directly (overrides --bundle)', (v) => parseInt(v, 10));
+        .option('--pid <n>', 'Target pid directly (overrides --bundle)', (v) => parseInt(v, 10))
+        .option('--host <device>', 'Drive a remote Windows device (requires `agents computer start --host <device>` first)');
 }
 // Add the shared --id/--x/--y element-or-coords options to a verb.
 function addElementOrCoordOpts(cmd) {

package/dist/commands/computer.d.ts

@@ -1,5 +1,17 @@
 import { Command } from 'commander';
 import { resolveHelperExec, resolveSocketPath } from '../lib/computer-rpc.js';
+/**
+ * Pure platform gate. The computer subsystem is macOS-only for LOCAL driving
+ * (Accessibility / launchctl). It is NOT blocked off macOS when a remote daemon
+ * is reachable — either a configured TCP endpoint (COMPUTER_HELPER_TCP, e.g. a
+ * Windows daemon over a tunnel) or a `--host <device>` remote invocation. Kept
+ * pure so the gating rule is unit-testable without a live command tree.
+ */
+export declare function shouldBlockOffPlatform(opts: {
+    platform: NodeJS.Platform;
+    tcpConfigured: boolean;
+    host?: string;
+}): boolean;
 export declare function registerComputerCommand(program: Command): void;
 export declare function registerComputerSubcommands(program: Command): void;
 export { resolveHelperExec as resolveHelperPath };

package/dist/commands/computer.js

@@ -3,7 +3,8 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
-import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
+import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, resolveTcpEndpoint, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
+import { setupRemoteHelper, startRemoteTunnel, stopRemoteHelper, hydrateRemoteEnvFromState, } from '../lib/ssh-tunnel.js';
 import { registerActionCommands, withClient, unwrap, pickTarget } from './computer-actions.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
 const COMPUTER_HELP_GROUPS = [
@@ -12,15 +13,44 @@ const COMPUTER_HELP_GROUPS = [
     { title: 'Observe', names: ['apps', 'describe', 'screenshot', 'get-text'] },
     { title: 'Interact', names: ['launch', 'raise', 'click', 'right-click', 'type', 'type-text', 'key', 'drag', 'scroll', 'ax-action', 'focus', 'wait'] },
 ];
+// Subcommands that manage the `--host` remote path themselves (provisioning /
+// tunnel lifecycle). Every other `--host`-bearing subcommand is a plain verb
+// that just needs the TCP endpoint hydrated before it runs.
+const REMOTE_LIFECYCLE = new Set(['setup', 'start', 'stop']);
+/**
+ * Pure platform gate. The computer subsystem is macOS-only for LOCAL driving
+ * (Accessibility / launchctl). It is NOT blocked off macOS when a remote daemon
+ * is reachable — either a configured TCP endpoint (COMPUTER_HELPER_TCP, e.g. a
+ * Windows daemon over a tunnel) or a `--host <device>` remote invocation. Kept
+ * pure so the gating rule is unit-testable without a live command tree.
+ */
+export function shouldBlockOffPlatform(opts) {
+    if (opts.platform === 'darwin')
+        return false;
+    if (opts.tcpConfigured)
+        return false; // remote (Windows) daemon over a tunnel
+    if (opts.host)
+        return false; // remote path resolves its own endpoint
+    return true;
+}
 export function registerComputerCommand(program) {
     const computer = program
         .command('computer')
-        .description('Drive macOS apps via Accessibility — list, screenshot, click, type (macOS only)')
-        // The whole subsystem is macOS Accessibility / TCC. Fail fast with a clear
-        // message on other platforms instead of a downstream ENOENT / launchctl error.
-        .hook('preAction', () => {
-        if (process.platform !== 'darwin') {
-            console.error('agents computer: macOS only — it drives apps via the macOS Accessibility API.');
+        .description('Drive macOS apps via Accessibility, or a remote Windows host with --host — list, screenshot, click, type')
+        // The whole subsystem is macOS Accessibility / TCC for LOCAL driving. Off
+        // macOS it still works against a remote daemon (COMPUTER_HELPER_TCP set, or
+        // a `--host <device>` invocation). Fail fast with a clear message only when
+        // neither remote path is available, instead of a downstream launchctl error.
+        .hook('preAction', async (_thisCommand, actionCommand) => {
+        const host = actionCommand.opts().host;
+        // Verbs with --host reconnect to the tunnel `start --host` recorded; this
+        // sets COMPUTER_HELPER_TCP so the shared client picks the TCP transport.
+        if (host && !REMOTE_LIFECYCLE.has(actionCommand.name())) {
+            hydrateRemoteEnvFromState(host);
+        }
+        if (shouldBlockOffPlatform({ platform: process.platform, tcpConfigured: resolveTcpEndpoint() != null, host })) {
+            console.error('agents computer: macOS only for local driving — it uses the macOS Accessibility API.');
+            console.error('For a remote Windows host: register it with `agents devices`, then use --host (or set COMPUTER_HELPER_TCP).');
             process.exit(1);
         }
     });
@@ -94,6 +124,7 @@ function registerScreenshotCommand(program) {
         .description('Capture a window (default: largest), enumerate windows (--list), or the whole display (--display)')
         .option('--bundle <id>', 'Bundle id to capture (default: frontmost allow-listed app)')
         .option('--pid <n>', 'Target pid directly (overrides --bundle)', (v) => parseInt(v, 10))
+        .option('--host <device>', 'Drive a remote Windows device (requires `agents computer start --host <device>` first)')
         .option('--list', 'List the app\'s windows (id/title/layer/bounds) instead of capturing — reveals modals/popups')
         .option('--window-id <n>', 'Capture a specific window by id (from --list)', (v) => parseInt(v, 10))
         .option('--display', 'Capture the whole display the app is on (composites stacked modals)')
@@ -181,8 +212,23 @@ function registerSetupCommand(program) {
     program
         .command('setup')
         .alias('install-helper')
-        .description('Install ComputerHelper.app to /Applications/ (does NOT activate the daemon — run `start` to enable)')
-        .action(async () => {
+        .description('Install the helper — locally to /Applications/ (macOS), or to a remote Windows host with --host')
+        .option('--host <device>', 'Provision a remote Windows device (push the exe + register a LOGON task) instead of installing locally')
+        .action(async (opts) => {
+        if (opts.host) {
+            try {
+                const { target, taskName } = await setupRemoteHelper(opts.host);
+                console.log(`pushed computer-helper-win.exe to ${target}`);
+                console.log(`registered LOGON scheduled task "${taskName}" (interactive session, started now)`);
+                console.log('');
+                console.log(`Next:  agents computer start --host ${opts.host}`);
+            }
+            catch (err) {
+                console.error(`error: ${err.message}`);
+                process.exit(1);
+            }
+            return;
+        }
         const srcApp = resolveHelperApp();
         if (!srcApp || !fs.existsSync(srcApp)) {
             console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
@@ -266,8 +312,24 @@ function registerSetupCommand(program) {
 function registerStartCommand(program) {
     program
         .command('start')
-        .description('Activate the helper daemon (loads launchd, opens socket)')
-        .action(async () => {
+        .description('Activate the helper daemon — local launchd (macOS) or a remote Windows tunnel with --host')
+        .option('--host <device>', 'Open a tunnel to the remote Windows daemon and record it for --host verbs')
+        .action(async (opts) => {
+        if (opts.host) {
+            try {
+                const state = await startRemoteTunnel(opts.host);
+                console.log(`tunnel: 127.0.0.1:${state.localPort} -> ${state.target} (127.0.0.1:${state.remotePort})`);
+                console.log(`daemon: answering (ssh pid ${state.tunnelPid})`);
+                console.log('');
+                console.log(`Drive it:  agents computer apps --host ${opts.host}`);
+                console.log(`Stop:      agents computer stop --host ${opts.host}`);
+            }
+            catch (err) {
+                console.error(`error: ${err.message}`);
+                process.exit(1);
+            }
+            return;
+        }
         const home = os.homedir();
         const plistPath = path.join(home, 'Library', 'LaunchAgents', `${HELPER_LABEL}.plist`);
         const socketPath = resolveSocketPath();
@@ -440,8 +502,21 @@ function registerReloadCommand(program) {
 function registerStopCommand(program) {
     program
         .command('stop')
-        .description('Deactivate the helper daemon (bootout, removes socket)')
-        .action(async () => {
+        .description('Deactivate the helper daemon — local launchd (macOS) or a remote Windows tunnel with --host')
+        .option('--host <device>', 'Tear down the remote tunnel and unregister the scheduled task')
+        .action(async (opts) => {
+        if (opts.host) {
+            try {
+                const { tunnelKilled, taskRemoved } = await stopRemoteHelper(opts.host);
+                console.log(`tunnel: ${tunnelKilled ? 'closed' : 'not running'}`);
+                console.log(`task:   ${taskRemoved ? 'unregistered' : 'not removed (device offline?)'}`);
+            }
+            catch (err) {
+                console.error(`error: ${err.message}`);
+                process.exit(1);
+            }
+            return;
+        }
         const home = os.homedir();
         const plistPath = path.join(home, 'Library', 'LaunchAgents', `${HELPER_LABEL}.plist`);
         const socketPath = resolveSocketPath();

package/dist/commands/inspect.js

@@ -1217,7 +1217,7 @@ function safeStat(p) {
     }
 }
 const SESSION_AGENTS = new Set([
-    'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi',
+    'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid',
 ]);
 function safeCountSessions(agent) {
     if (!SESSION_AGENTS.has(agent))

package/dist/commands/models.js

@@ -11,7 +11,7 @@ import { homeDir } from '../lib/platform/index.js';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
-const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'cursor', 'openclaw'];
+const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
  * via a curl script). For these, fall back to the PATH binary and synthesize
@@ -72,8 +72,14 @@ async function resolveTargets(agentSpec) {
             if (!version && PATH_ONLY_AGENTS.has(agent)) {
                 version = fallbackPathVersion(agent);
             }
-            if (version)
+            if (version) {
                 targets.push({ agent, version, isDefault: true });
+            }
+            else {
+                // Surface the gap instead of silently dropping the agent -- an
+                // uninstalled model-capable agent should tell the user how to add it.
+                console.error(chalk.gray(`${agentLabel(agent)}: not installed (run 'agents add ${agent}@latest')`));
+            }
         }
         if (targets.length === 0) {
             console.error(chalk.yellow('No installed agent versions found. Run `agents add claude@latest` to install one.'));

package/dist/commands/sessions.js

@@ -17,6 +17,7 @@ import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
 import { looksLikePath, toComparablePath, homeDir } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
@@ -162,43 +163,77 @@ function formatStartedAt(startedAtMs) {
         return '-';
     return formatRelativeTime(new Date(startedAtMs).toISOString());
 }
-/** Build a display-friendly description for an active session (label or topic). */
+/**
+ * Build the live description for an active session: prefer the state engine's
+ * preview (the latest turn), then a user label, then the first-prompt topic.
+ */
 function buildSessionDescription(s) {
     if (s.context === 'cloud') {
-        return `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
+        return s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
     }
     if (s.context === 'teams') {
         const parts = [s.teamName];
-        if (s.label)
+        if (s.preview)
+            parts.push(s.preview);
+        else if (s.label)
             parts.push(s.label);
         else if (s.topic)
             parts.push(s.topic);
         return parts.filter(Boolean).join(' · ');
     }
-    // Terminal or headless: prefer label, then topic
-    if (s.label)
-        return s.label;
-    if (s.topic)
-        return s.topic;
-    return '';
+    // Terminal or headless: prefer the live preview, then label, then topic.
+    return s.preview || s.label || s.topic || '';
+}
+/** Short human word for a session's activity (falls back to the coarse status). */
+function activityLabel(s) {
+    if (s.activity === 'waiting_input')
+        return 'waiting';
+    if (s.activity === 'working')
+        return 'working';
+    if (s.activity === 'idle')
+        return 'idle';
+    return s.status === 'input_required' ? 'waiting' : s.status;
+}
+/**
+ * Compact, colour-coded badges for the durable/awaiting signals. Text-only (no
+ * emoji, per repo convention): `plan` / `ask` / `perm` for why it's waiting,
+ * `PR#N`, `wt:slug`, `TICKET-123`.
+ */
+function signalBadges(s) {
+    const parts = [];
+    if (s.awaitingReason === 'plan_review')
+        parts.push(chalk.yellow('plan'));
+    else if (s.awaitingReason === 'question')
+        parts.push(chalk.yellow('ask'));
+    else if (s.awaitingReason === 'permission')
+        parts.push(chalk.yellow('perm'));
+    if (s.ticket)
+        parts.push(chalk.cyan(s.ticket.id));
+    if (s.pr)
+        parts.push(chalk.blue(`PR#${s.pr.number ?? '?'}`));
+    if (s.worktree)
+        parts.push(chalk.magenta(`wt:${s.worktree.slug}`));
+    return parts.join(' ');
 }
 /**
  * Render a single agent-session row inside an already-printed group header.
  * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a
- * window sub-group).
+ * window sub-group). Leads with the 8-char session id (the address to read or
+ * resume it); status, badges, and the live preview fill the rest, sized to the
+ * terminal width so the row never wraps.
  */
 function printActiveRow(s, indent) {
-    const kindCol = colorAgent(s.kind)(padRight(truncate(s.kind, 8), 9));
-    const hostCol = chalk.gray(padRight(truncate(s.host ?? '-', 8), 9));
-    const statusCol = statusColor(s.status)(padRight(truncate(s.status, 7), 8));
-    const pidCol = chalk.yellow(padRight(s.pid ? String(s.pid) : '-', 7));
-    const desc = buildSessionDescription(s);
-    console.log(indent +
-        pidCol +
-        kindCol +
-        hostCol +
-        statusCol +
-        chalk.white(truncate(desc || '-', 50)));
+    const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', 9));
+    const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, 8), 9));
+    const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
+    const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
+    const badges = signalBadges(s);
+    const desc = buildSessionDescription(s) || '-';
+    // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
+    const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
+    const room = Math.max(12, terminalWidth() - fixed - 1);
+    const descCol = chalk.white(truncateToWidth(desc, room));
+    console.log(indent + idCol + kindCol + hostCol + statusCol + (badges ? badges + ' ' : '') + descCol);
 }
 /**
  * Short label for an IDE window. The slice key in live-terminals.json is
@@ -266,14 +301,21 @@ export function groupActiveSessions(sessions) {
     return { workspaces };
 }
 /** Render the unified active-session view. */
-async function renderActiveSessions(asJson) {
-    const sessions = await getActiveSessions();
+async function renderActiveSessions(asJson, waitingOnly = false) {
+    const all = await getActiveSessions();
+    // --waiting: only sessions blocked on the user. Exits non-zero when any are
+    // present so a supervising agent or hook can poll it as a gate.
+    const sessions = waitingOnly
+        ? all.filter(s => s.status === 'input_required')
+        : all;
     if (asJson) {
         process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+        if (waitingOnly && sessions.length > 0)
+            process.exitCode = 1;
         return;
     }
     if (sessions.length === 0) {
-        console.log(chalk.gray('No active agent sessions.'));
+        console.log(chalk.gray(waitingOnly ? 'No sessions waiting on input.' : 'No active agent sessions.'));
         return;
     }
     const layout = groupActiveSessions(sessions);
@@ -312,6 +354,9 @@ async function renderActiveSessions(asJson) {
     if (queuedCount > 0)
         parts.push(`${queuedCount} queued`);
     console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}).`));
+    // Scriptable gate: a non-zero exit when anything is waiting on the user.
+    if (waitingOnly && sessions.length > 0)
+        process.exitCode = 1;
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
@@ -326,7 +371,7 @@ async function sessionsAction(query, options) {
         return;
     }
     if (options.active) {
-        await renderActiveSessions(options.json === true);
+        await renderActiveSessions(options.json === true, options.waiting === true);
         return;
     }
     if (options.cloud) {
@@ -455,7 +500,9 @@ async function sessionsAction(query, options) {
             }
             return;
         }
-        if (isInteractiveTerminal()) {
+        // --tree is a printed grouped listing, not an interactive pick — render it
+        // directly even in a TTY.
+        if (isInteractiveTerminal() && !options.tree) {
             const message = pathFilter
                 ? `Search sessions (${path.basename(pathFilter)}):`
                 : formatSearchMessage(options);
@@ -468,7 +515,7 @@ async function sessionsAction(query, options) {
         }
         // Non-interactive fallback (piped output)
         const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
-        printSessionTable(filtered, hiddenCount);
+        printSessionTable(filtered, hiddenCount, options.tree === true);
     }
     catch (err) {
         tracker.stop();
@@ -487,22 +534,83 @@ function teamTag(session) {
     const parts = [origin.handle, origin.mode].filter(Boolean).join(' · ');
     return parts ? `[${parts}] ` : '[team] ';
 }
-function printSessionTable(sessions, hiddenCount = 0) {
-    for (const session of sessions) {
-        const agentColor = colorAgent(session.agent);
-        const when = formatRelativeTime(session.timestamp);
-        const project = session.project || '-';
-        const tag = teamTag(session);
-        const label = session.label;
-        const topic = tag ? `${tag}${session.topic ?? ''}` : session.topic;
-        const versionStr = session.version || '-';
-        console.log(chalk.white(padRight(session.shortId, 10)) +
-            agentColor(padRight(truncate(session.agent, 8), 9)) +
-            chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
-            chalk.cyan(padRight(truncate(project, 14), 16)) +
-            renderTopicCell(label, topic, '', 48, 50) +
-            chalk.gray(when));
+/** Adapt a SessionMeta's persisted signals to the badge renderer's shape. */
+function metaSignals(s) {
+    return {
+        pr: s.prUrl ? { url: s.prUrl, number: s.prNumber } : undefined,
+        worktree: s.worktreeSlug ? { path: s.cwd ?? '', slug: s.worktreeSlug } : undefined,
+        ticket: s.ticketId ? { id: s.ticketId } : undefined,
+    };
+}
+/** One flat table row: shortId · agent · version · project · topic(+badges) · time. */
+function flatSessionRow(session) {
+    const agentColor = colorAgent(session.agent);
+    const when = formatRelativeTime(session.timestamp);
+    const project = session.project || '-';
+    const tag = teamTag(session);
+    const label = session.label;
+    const topic = tag ? `${tag}${session.topic ?? ''}` : session.topic;
+    const versionStr = session.version || '-';
+    const badges = signalBadges(metaSignals(session));
+    const badgeW = badges ? stringWidth(badges) + 1 : 0;
+    const topicW = Math.max(16, terminalWidth() - (10 + 9 + 8 + 16) - badgeW - stringWidth(when) - 1);
+    return (chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
+        agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
+        chalk.yellow(padToWidth(truncateToWidth(versionStr, 7), 8)) +
+        chalk.cyan(padToWidth(truncateToWidth(project, 14), 16)) +
+        renderTopicCell(label, topic, '', topicW, topicW) +
+        (badges ? badges + ' ' : '') +
+        chalk.gray(when));
+}
+/** One tree-mode row (grouped under a dir header): id · agent · badges · topic · time. No version/project column. */
+function treeSessionRow(session) {
+    const agentColor = colorAgent(session.agent);
+    const when = formatRelativeTime(session.timestamp);
+    const tag = teamTag(session);
+    const label = session.label;
+    const topic = (tag ? `${tag}${session.topic ?? ''}` : session.topic) || '-';
+    const badges = signalBadges(metaSignals(session));
+    const badgeW = badges ? stringWidth(badges) + 1 : 0;
+    const head = label ? `${label} · ${topic}` : topic;
+    const topicW = Math.max(12, terminalWidth() - (2 + 9 + 8) - badgeW - stringWidth(when) - 1);
+    return ('  ' +
+        chalk.dim(padToWidth(session.shortId, 9)) +
+        agentColor(padToWidth(truncateToWidth(session.agent, 7), 8)) +
+        (badges ? badges + ' ' : '') +
+        padToWidth(chalk.white(truncateToWidth(head, topicW)), topicW) +
+        ' ' + chalk.gray(when));
+}
+function printSessionTable(sessions, hiddenCount = 0, tree = false) {
+    if (tree) {
+        // Group by directory; drop the id/version columns from view. The short id
+        // stays as each row's leading handle (the address to read/resume it).
+        const byDir = new Map();
+        for (const s of sessions) {
+            const key = s.cwd || s.project || 'unknown';
+            (byDir.get(key) ?? byDir.set(key, []).get(key)).push(s);
+        }
+        const keys = [...byDir.keys()].sort((a, b) => {
+            const d = byDir.get(b).length - byDir.get(a).length;
+            return d !== 0 ? d : a.localeCompare(b);
+        });
+        let first = true;
+        for (const key of keys) {
+            if (!first)
+                console.log();
+            first = false;
+            const group = byDir.get(key);
+            console.log(`${chalk.cyan.bold(shortCwd(key))} ${chalk.gray(`(${group.length})`)}`);
+            for (const s of group)
+                console.log(treeSessionRow(s));
+        }
+        const dirWord = keys.length === 1 ? 'directory' : 'directories';
+        console.log(chalk.gray(`\n${sessions.length} session${sessions.length === 1 ? '' : 's'} across ${keys.length} ${dirWord}.`));
+        if (hiddenCount > 0)
+            console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+        return;
     }
+    for (const session of sessions)
+        console.log(flatSessionRow(session));
     const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
     console.log(chalk.gray(`\n${countLine}`));
     if (hiddenCount > 0) {
@@ -608,8 +716,10 @@ function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
     const tpc = (topic ?? '').trim();
     const sep = ' · ';
     const raw = lbl && tpc ? `${lbl}${sep}${tpc}` : (lbl || tpc);
-    const visible = truncate(raw, visibleWidth);
-    const padding = ' '.repeat(Math.max(0, paddedWidth - visible.length));
+    // Width-aware: measure/truncate/pad by display cells, not String.length, so
+    // ANSI escapes and wide (CJK/emoji) glyphs don't drift the column.
+    const visible = truncateToWidth(raw, visibleWidth);
+    const padding = ' '.repeat(Math.max(0, paddedWidth - stringWidth(visible)));
     const labelEnd = lbl ? Math.min(lbl.length, visible.length) : 0;
     let matchStart = -1, matchEnd = -1;
     const q = query.trim().toLowerCase();
@@ -1129,6 +1239,8 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
+        .option('--waiting', 'With --active: show only sessions waiting on your input (exits non-zero if any)')
+        .option('--tree', 'Group the listing by directory; drops the id/version columns for readability')
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)');
     setHelpSections(sessionsCmd, {