@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/commands/sessions.js

@@ -15,15 +15,18 @@ import chalk from 'chalk';
 import ora from 'ora';
 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 { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecutable } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
+import { mapPanesToTargets } from '../lib/tmux/session.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
-import { gatherRemoteActive } from '../lib/session/remote-active.js';
+import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
+import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.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';
-import { runRemoteSessions } from '../lib/session/remote.js';
+import { runRemoteSessions, buildForwardedArgs } from '../lib/session/remote.js';
 import { formatRelativeTime } from '../lib/session/relative-time.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
@@ -36,7 +39,26 @@ import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
+import { registerSessionsInjectCommand } from './sessions-inject.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
+/**
+ * The prioritized harnesses that get a boolean shorthand flag (e.g. `--claude`
+ * === `--agent claude`). The rest stay reachable via `--agent <name>`, which
+ * also carries version pins like `codex@0.116.0`.
+ */
+const AGENT_SHORTHANDS = ['claude', 'codex', 'kimi', 'antigravity', 'grok', 'opencode'];
+/**
+ * Resolve a per-agent shorthand (`--claude`, `--kimi`, …) into `options.agent`.
+ * An explicit `--agent` wins; if two shorthands are passed we take the first and
+ * ignore the rest (commander gives no ordering, so this is a best-effort alias).
+ */
+function applyAgentShorthands(options) {
+    if (options.agent)
+        return;
+    const hit = AGENT_SHORTHANDS.find((name) => options[name] === true);
+    if (hit)
+        options.agent = hit;
+}
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
 const FIND_VERBS = ['Finding', 'Searching', 'Locating', 'Matching'];
@@ -78,6 +100,12 @@ function createScanProgressTracker(verbs, suffix, spinner) {
 }
 const PICKER_RECENT_COUNT = 15;
 const PICKER_POOL_LIMIT = 200;
+// The grouped default view ("overview"): fetch a generous recency-ordered pool
+// for accurate per-project totals, show each project's most-recent rows grouped
+// by project, newest-active project first.
+const OVERVIEW_ROWS_PER_PROJECT = 5; // recent rows shown per project before "· N more"
+const OVERVIEW_POOL_LIMIT = 1000; // fetch cap — accurate per-project totals up to this
+const OVERVIEW_MAX_PROJECTS = 12; // project groups shown before "+N more projects"
 /**
  * Resolve a path-like query to an absolute directory path.
  */
@@ -166,13 +194,28 @@ function formatStartedAt(startedAtMs) {
         return '-';
     return formatRelativeTime(new Date(startedAtMs).toISOString());
 }
+/**
+ * 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
+ * (`<local-command-stdout>`, `<task-notification>`, `<command-*>`) that leak from
+ * a captured transcript tail. Collapses runs of whitespace.
+ */
+export function cleanPreview(text) {
+    // eslint-disable-next-line no-control-regex
+    return text
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '') // OSC (title) sequences
+        .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '') // CSI / SGR ANSI
+        .replace(/<\/?(?:local-command-stdout|command-name|command-message|command-args|task-notification|system-reminder)>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 /**
  * 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.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
+        return cleanPreview(s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`);
     }
     if (s.context === 'teams') {
         const parts = [s.teamName];
@@ -182,10 +225,10 @@ function buildSessionDescription(s) {
             parts.push(s.label);
         else if (s.topic)
             parts.push(s.topic);
-        return parts.filter(Boolean).join(' · ');
+        return cleanPreview(parts.filter(Boolean).join(' · '));
     }
     // Terminal or headless: prefer the live preview, then label, then topic.
-    return s.preview || s.label || s.topic || '';
+    return cleanPreview(s.preview || s.label || s.topic || '');
 }
 /** Short human word for a session's activity (falls back to the coarse status). */
 function activityLabel(s) {
@@ -256,20 +299,25 @@ function signalBadges(s) {
     return parts.join(' ');
 }
 /**
- * Compact provenance badge: how to reach the session, not what it's doing.
- * `ssh` flags a remote host; the tmux pane id is the send-keys target the feed
- * would type back into. Local, non-tmux sessions add nothing (the common case).
+ * Compact locator badge: how to JUMP to the session, not what it's doing.
+ * `ssh` flags a remote host. For tmux, prefer the resolved `session:window.pane`
+ * (a real `tmux attach -t <session:window>` target) over the raw `%pane` id. For
+ * a local Ghostty session we know the tab, show `tab N`. Local, unlocatable
+ * sessions add nothing (the common case).
  */
-function provenanceBadge(p) {
-    if (!p)
-        return '';
+function locatorBadge(s) {
+    const p = s.provenance;
     const parts = [];
-    if (p.transport === 'ssh')
+    if (p?.transport === 'ssh')
         parts.push(chalk.red('ssh'));
-    if (p.mux?.kind === 'tmux' && p.mux.pane)
-        parts.push(chalk.green(`tmux ${p.mux.pane}`));
-    else if (p.mux?.kind === 'screen')
+    if (p?.mux?.kind === 'tmux' && (s.tmuxTarget || p.mux.pane)) {
+        parts.push(chalk.green(s.tmuxTarget ?? p.mux.pane));
+    }
+    else if (p?.mux?.kind === 'screen') {
         parts.push(chalk.green('screen'));
+    }
+    if (s.ghosttyTab != null)
+        parts.push(chalk.green(`tab ${s.ghosttyTab}`));
     return parts.join(' ');
 }
 /**
@@ -285,7 +333,7 @@ function printActiveRow(s, indent) {
     const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
-    const badges = (fork ? fork : '') + [signalBadges(s), provenanceBadge(s.provenance)].filter(Boolean).join(' ');
+    const badges = (fork ? fork : '') + [signalBadges(s), locatorBadge(s)].filter(Boolean).join(' ');
     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);
@@ -423,6 +471,62 @@ export function dedupeByMachineSession(sessions) {
     }
     return out;
 }
+/**
+ * Order a merged listing so the local machine's sessions come first, then each
+ * remote machine as a contiguous block (more sessions first, then name), with
+ * every machine keeping its incoming order (timestamp) within the block. Also
+ * dedupes: a session present both locally (a synced mirror copy) and via live
+ * fan-out collapses to one, keyed by machine + session id. Rows are keyed by
+ * `machine` (discover tags local rows with the local id; fan-out tags remote
+ * rows with the peer id) falling back to `localMachine` when untagged. Pure —
+ * `localMachine` is injected so the ordering is testable without os.hostname().
+ */
+export function mergeLocalFirst(sessions, localMachine) {
+    const byMachine = new Map();
+    const seen = new Set();
+    for (const s of sessions) {
+        const machine = s.machine || localMachine;
+        if (s.id) {
+            const dedupeKey = `${machine}:${s.id}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+        }
+        (byMachine.get(machine) ?? byMachine.set(machine, []).get(machine)).push(s);
+    }
+    const keys = Array.from(byMachine.keys()).sort((a, b) => {
+        if (a === localMachine)
+            return -1;
+        if (b === localMachine)
+            return 1;
+        const ac = byMachine.get(a).length, bc = byMachine.get(b).length;
+        if (ac !== bc)
+            return bc - ac;
+        return a.localeCompare(b);
+    });
+    return keys.flatMap((k) => byMachine.get(k));
+}
+/**
+ * `running N · idle N · waiting N · queued N` for a bucket of sessions (zero
+ * buckets omitted). Same bucketing as the grand-total summary so per-group
+ * counts reconcile with the `(total)` beside the header. Empty when nothing.
+ */
+function groupTally(sessions) {
+    const running = sessions.filter(s => s.status === 'running').length;
+    const idle = sessions.filter(s => s.status === 'idle').length;
+    const waiting = sessions.filter(s => s.status === 'input_required').length;
+    const queued = sessions.filter(s => s.status === 'queued').length;
+    const parts = [];
+    if (running)
+        parts.push(`${running} running`);
+    if (idle)
+        parts.push(`${idle} idle`);
+    if (waiting)
+        parts.push(`${waiting} waiting`);
+    if (queued)
+        parts.push(`${queued} queued`);
+    return parts.join(' · ');
+}
 /** Print one machine's workspace tree, indented under its machine header. */
 function renderWorkspaceLayout(layout, base) {
     let first = true;
@@ -435,7 +539,9 @@ function renderWorkspaceLayout(layout, base) {
             : ws.key === '__unknown__'
                 ? chalk.gray.bold('unknown')
                 : chalk.cyan.bold(shortCwd(ws.key));
-        console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}`);
+        const wsSessions = [...ws.windows.flatMap(w => w.sessions), ...ws.flat];
+        const tally = groupTally(wsSessions);
+        console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}${tally ? chalk.gray(`  ${tally}`) : ''}`);
         for (const win of ws.windows) {
             // Host is per-process, but every terminal in the same IDE window shares
             // an ancestor — take the first non-empty host as the window's label.
@@ -457,6 +563,43 @@ function printMachineHeader(mg) {
     const here = mg.isLocal ? chalk.cyan('  ← this machine') : '';
     console.log(`${marker}${name} ${chalk.gray(`(${mg.total})`)}${here}`);
 }
+/**
+ * Attach display-only jump locators onto LOCAL sessions: the Ghostty tab number
+ * (one batched read-only osascript, only when a local ghostty session exists)
+ * and the tmux `session:window.pane` target (one `list-panes -a` per socket).
+ * Every step is best-effort and swallowed — a failure just leaves the raw pane
+ * id / no tab number, and the rows render as before. Mutates the sessions.
+ */
+async function enrichLocalLocators(local) {
+    // Ghostty tab numbers.
+    try {
+        const ghostty = local.filter(s => s.host === 'ghostty' && s.provenance?.transport !== 'ssh');
+        if (ghostty.length > 0) {
+            const surfaces = await enumerateGhosttyTabs();
+            for (const [sess, tab] of assignGhosttyTabs(ghostty, surfaces))
+                sess.ghosttyTab = tab;
+        }
+    }
+    catch { /* non-fatal */ }
+    // tmux attach targets, one batched query per distinct socket.
+    try {
+        const tmux = local.filter(s => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
+        const sockets = new Set(tmux.map(s => s.provenance.mux.socket));
+        for (const socket of sockets) {
+            const paneMap = await mapPanesToTargets(socket);
+            if (paneMap.size === 0)
+                continue;
+            for (const s of tmux) {
+                if (s.provenance.mux.socket !== socket)
+                    continue;
+                const target = paneMap.get(s.provenance.mux.pane);
+                if (target)
+                    s.tmuxTarget = target;
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+}
 /**
  * Render the unified active-session view, grouped by machine. Local sessions
  * come from `getActiveSessions()`; unless `--local`, sessions from other
@@ -492,6 +635,10 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
             printCrossMachineTip();
         return;
     }
+    // Enrich LOCAL sessions with jump locators (display-only, after the --json /
+    // --waiting gates so scriptable output stays osascript-free). Remote sessions
+    // keep their raw pane id — their tmux/Ghostty live on the other machine.
+    await enrichLocalLocators(sessions.filter(s => !s.machine || s.machine === self));
     const grouped = groupSessionsByMachine(sessions, self);
     let firstMachine = true;
     for (const mg of grouped.machines) {
@@ -501,16 +648,7 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
         printMachineHeader(mg);
         renderWorkspaceLayout(mg.layout, '  ');
     }
-    const runningCount = sessions.filter(s => s.status === 'running').length;
-    const idleCount = sessions.filter(s => s.status === 'idle').length;
-    const queuedCount = sessions.filter(s => s.status === 'queued' || s.status === 'input_required').length;
-    const parts = [];
-    if (runningCount > 0)
-        parts.push(`${runningCount} running`);
-    if (idleCount > 0)
-        parts.push(`${idleCount} idle`);
-    if (queuedCount > 0)
-        parts.push(`${queuedCount} queued`);
+    const parts = groupTally(sessions).split(' · ').filter(Boolean);
     const machineWord = grouped.machines.length === 1 ? 'machine' : 'machines';
     console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}) across ${grouped.machines.length} ${machineWord}.`));
     // Tip only when nothing else could be included and the user didn't opt out.
@@ -526,6 +664,13 @@ function printCrossMachineTip() {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    // Normalize convenience flags before any routing reads them: per-agent
+    // shorthands fold into --agent, and --device is an alias for --host (both
+    // resolve against the same device registry).
+    applyAgentShorthands(options);
+    if (options.device && options.device.length > 0) {
+        options.host = [...(options.host ?? []), ...options.device];
+    }
     // --host WITHOUT --active keeps the legacy per-host stream (each remote's raw
     // stdout under a `── host ──` banner). With --active, the hosts are folded
     // into the merged machine-grouped view instead (handled below).
@@ -599,8 +744,18 @@ async function sessionsAction(query, options) {
     // Interactive picker loads a deep pool but shows only recent sessions
     // until the user starts typing. Non-interactive/JSON uses the explicit limit.
     const isInteractive = !options.json && isInteractiveTerminal();
-    const limit = parseInt(options.limit || (isInteractive ? String(PICKER_POOL_LIMIT) : '50'), 10);
-    const since = options.since ?? (isInteractive && !options.all ? '30d' : undefined);
+    // The grouped project overview is the default for a bare interactive listing:
+    // no query, no path drill-in, not explicitly --flat/--tree. It drops the silent
+    // cwd-scope + 50-cap + 30-day window that hide most of a large index.
+    const wantsOverview = isInteractive && !searchQuery && !pathFilter && !options.flat && !options.tree;
+    const limit = wantsOverview
+        ? OVERVIEW_POOL_LIMIT
+        : parseInt(options.limit || (isInteractive ? String(PICKER_POOL_LIMIT) : '50'), 10);
+    // Overview: recency order across the whole index, no default window; an explicit
+    // --since still narrows. Non-overview keeps the prior interactive-30d default.
+    const since = wantsOverview
+        ? options.since
+        : (options.since ?? (isInteractive && !options.all ? '30d' : undefined));
     const spinner = options.json ? null : ora().start();
     const tracker = createScanProgressTracker(LOAD_VERBS, 'sessions', spinner);
     try {
@@ -615,7 +770,10 @@ async function sessionsAction(query, options) {
             version,
             all: pathFilter ? undefined : options.all,
             cwd: process.cwd(),
-            cwdPrefix: pathFilter,
+            // Default overview scopes to the current repo SUBTREE (prefix match), so a
+            // monorepo shows its sub-projects grouped instead of collapsing to the one
+            // exact-cwd project. `--all` clears the prefix and spans the whole index.
+            cwdPrefix: pathFilter ?? (wantsOverview && !options.all ? process.cwd() : undefined),
             project: options.project,
             since,
             until: options.until,
@@ -657,12 +815,42 @@ async function sessionsAction(query, options) {
         if (options.json) {
             const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
             const serializable = filtered.map(s => {
-                const { _matchedTerms, _bm25Score, ...rest } = s;
+                const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
                 return rest;
             });
             process.stdout.write(JSON.stringify(serializable, null, 2) + '\n');
             return;
         }
+        // Cross-machine fan-out: unless --local (or we ARE a peer answering a
+        // parent's sweep), fold in other online machines' sessions live over SSH so
+        // the list spans the fleet without any sync — each remote row carries the
+        // machine it came from, and the picker/table label + group by it. Only the
+        // interactive picker and the printed table get this; --json and single-id
+        // resolution above stay local (a peer answers for itself; scripts get a
+        // deterministic local slice). Best-effort: a fan-out failure leaves the
+        // local list intact rather than erroring the whole command.
+        const forceLocal = options.local === true || process.env[NO_FANOUT_ENV] === '1';
+        if (!forceLocal) {
+            // Pass the hosts set so a variadic `--host a b` never leaks a host as a
+            // query (defensive: the --host-without-active early return above already
+            // means we only get here in auto-discovery mode, with no --host in argv).
+            const forwarded = buildForwardedArgs(process.argv, new Set(options.host ?? []));
+            if (!forwarded.includes('--json'))
+                forwarded.push('--json');
+            const fanSpinner = isInteractiveTerminal() ? ora('Reaching other machines...').start() : null;
+            try {
+                const { sessions: remoteSessions } = await gatherRemoteList(forwarded, options.host);
+                if (remoteSessions.length > 0) {
+                    sessions = mergeLocalFirst([...sessions, ...remoteSessions], machineId());
+                }
+            }
+            catch {
+                // fan-out is an enrichment, never a hard dependency
+            }
+            finally {
+                fanSpinner?.stop();
+            }
+        }
         if (sessions.length === 0) {
             if (pathFilter) {
                 console.log(chalk.gray(`No sessions found for ${pathFilter}.`));
@@ -675,9 +863,19 @@ async function sessionsAction(query, options) {
             }
             return;
         }
-        // --tree is a printed grouped listing, not an interactive pick — render it
-        // directly even in a TTY.
-        if (isInteractiveTerminal() && !options.tree) {
+        // The grouped project overview is the bare interactive default: a scannable
+        // dashboard of the whole fleet grouped by project, newest-active first.
+        // Interact/resume via `agents sessions <project>` or `agents sessions resume`.
+        if (wantsOverview) {
+            const liveIndex = await maybeLiveIndex(options);
+            // Per-project row cap is fixed (--limit carries a default of 50 and drives
+            // the fetch pool, not the display); `--all` expands every group instead.
+            printSessionOverview(sessions, hiddenCount, liveIndex, { perProjectCap: OVERVIEW_ROWS_PER_PROJECT, expand: !!options.all });
+            return;
+        }
+        // --tree / --flat are printed listings, not an interactive pick — render them
+        // directly even in a TTY. A search query keeps the interactive picker.
+        if (isInteractiveTerminal() && !options.tree && !options.flat) {
             const message = pathFilter
                 ? `Search sessions (${path.basename(pathFilter)}):`
                 : formatSearchMessage(options);
@@ -688,7 +886,7 @@ async function sessionsAction(query, options) {
             }
             return;
         }
-        // Non-interactive fallback (piped output)
+        // Non-interactive fallback (piped output) or --flat/--tree.
         const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
         const liveIndex = await maybeLiveIndex(options);
         printSessionTable(filtered, hiddenCount, options.tree === true, liveIndex);
@@ -724,9 +922,9 @@ function metaSignals(s) {
  * (tracker/PR ref, pulled out of the badge blob so refs align) is only rendered
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
-function flatSessionRow(session, live, showTicket = false) {
+function flatSessionRow(session, live, showTicket = false, cols = {}) {
     const agentColor = colorAgent(session.agent);
-    const when = formatRelativeTime(session.timestamp);
+    const when = formatRelativeTime(session.lastActivity ?? session.timestamp);
     const project = session.project || '-';
     const tag = teamTag(session);
     const label = session.label;
@@ -735,17 +933,26 @@ function flatSessionRow(session, live, showTicket = false) {
     // resting one falls back to its opening topic.
     const doing = preview || (tag ? `${tag}${session.topic ?? ''}` : session.topic);
     const wt = session.worktreeSlug ? chalk.magenta(`wt:${session.worktreeSlug}`) : '';
+    // The machine column only earns its width when the listing spans more than one
+    // box (i.e. the cross-machine fan-out folded remotes in) — same rule and
+    // pool-derived width as the picker.
+    const machineColW = cols.machineWidth ?? PICKER_MACHINE_W;
+    const machineCell = cols.showMachine
+        ? chalk.gray(padToWidth(truncateToWidth((cols.machineLabel?.(session.machine ?? '') ?? session.machine ?? '') || '-', machineColW - 1), machineColW))
+        : '';
     const TICKET_W = 10;
     const ticketCell = showTicket
         ? chalk.blue(padToWidth(truncateToWidth(ticketLabel(session) || '-', TICKET_W), TICKET_W + 1))
         : '';
     const glyphW = glyph ? 2 : 0;
+    const machineW = cols.showMachine ? machineColW : 0;
     const ticketW = showTicket ? TICKET_W + 1 : 0;
     const wtW = wt ? stringWidth(wt) + 1 : 0;
-    const topicW = Math.max(16, terminalWidth() - (10 + 9 + 8 + 16) - glyphW - ticketW - wtW - stringWidth(when) - 1);
+    const topicW = Math.max(16, terminalWidth() - (10 + 9 + 8 + 16) - glyphW - machineW - ticketW - wtW - stringWidth(when) - 1);
     return (chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
         agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
         chalk.yellow(padToWidth(truncateToWidth(session.version || '-', 7), 8)) +
+        machineCell +
         chalk.cyan(padToWidth(truncateToWidth(project, 14), 16)) +
         (glyph ? glyph + ' ' : '') +
         renderTopicCell(label, doing, '', topicW, topicW) +
@@ -756,7 +963,7 @@ function flatSessionRow(session, live, showTicket = false) {
 /** One tree-mode row (grouped under a dir header): id · agent · badges · topic · time. No version/project column. */
 function treeSessionRow(session, live) {
     const agentColor = colorAgent(session.agent);
-    const when = formatRelativeTime(session.timestamp);
+    const when = formatRelativeTime(session.lastActivity ?? session.timestamp);
     const tag = teamTag(session);
     const label = session.label;
     const { glyph, preview } = liveGlyphAndPreview(live);
@@ -793,6 +1000,79 @@ async function maybeLiveIndex(options) {
         return undefined;
     }
 }
+/**
+ * Group key for the overview: prefer the indexed project name; else fold the cwd
+ * to its repo — a worktree (`.../<repo>/.agents/worktrees/<slug>`) folds to the
+ * repo, and a monorepo subdir falls back to its leaf dir basename. Pure.
+ */
+export function overviewProjectKey(s) {
+    if (s.project && s.project.trim())
+        return s.project.trim();
+    const cwd = (s.cwd ?? '').replace(/\/+$/, '');
+    if (!cwd)
+        return '(no project)';
+    const wt = cwd.match(/\/([^/]+)\/\.agents\/worktrees\//);
+    if (wt)
+        return wt[1];
+    const parts = cwd.split('/');
+    return parts[parts.length - 1] || cwd;
+}
+/**
+ * Turn a recency-descending pool into project groups: each group shows its
+ * `perProjectCap` most-recent sessions (the rest become `· N more`), and groups
+ * are ordered by their most-recent session so the newest-active project leads.
+ * `perProjectCap = Infinity` expands every group. Pure — unit-tested.
+ */
+export function buildOverviewGroups(pool, perProjectCap) {
+    const byKey = new Map();
+    for (const s of pool) {
+        const k = overviewProjectKey(s);
+        (byKey.get(k) ?? byKey.set(k, []).get(k)).push(s);
+    }
+    const cap = Math.max(1, perProjectCap);
+    const groups = [];
+    for (const [key, rows] of byKey) {
+        const shown = rows.slice(0, cap); // rows are recency-desc (pool was sorted)
+        groups.push({ key, total: rows.length, shown, more: rows.length - shown.length, maxTs: rows[0].lastActivity ?? rows[0].timestamp });
+    }
+    groups.sort((a, b) => (a.maxTs < b.maxTs ? 1 : a.maxTs > b.maxTs ? -1 : a.key.localeCompare(b.key)));
+    return { groups, projectCount: byKey.size };
+}
+/**
+ * The grouped project overview — the bare interactive default. Shows the latest
+ * sessions grouped under their project, newest-active project first, with a
+ * `· N more` per project and a `+N more projects` when the list is capped.
+ */
+function printSessionOverview(pool, hiddenCount, liveIndex, opts) {
+    const { groups } = buildOverviewGroups(pool, opts.expand ? Infinity : opts.perProjectCap);
+    const shownGroups = opts.expand ? groups : groups.slice(0, OVERVIEW_MAX_PROJECTS);
+    const hiddenProjects = groups.length - shownGroups.length;
+    const total = pool.length;
+    const projWord = groups.length === 1 ? 'project' : 'projects';
+    console.log(chalk.gray(`${total} session${total === 1 ? '' : 's'} · ${groups.length} ${projWord} · recent activity\n`));
+    let first = true;
+    for (const g of shownGroups) {
+        if (!first)
+            console.log();
+        first = false;
+        const { glyph } = liveGlyphAndPreview(liveIndex?.get(g.shown[0].id));
+        const head = `${chalk.cyan('▸')} ${chalk.cyan.bold(g.key)}  ${chalk.gray(String(g.total))}` +
+            `${glyph ? '  ' + glyph : ''} ${chalk.gray(formatRelativeTime(g.maxTs))}`;
+        console.log(head);
+        for (const s of g.shown)
+            console.log(treeSessionRow(s, liveIndex?.get(s.id)));
+        if (g.more > 0)
+            console.log('  ' + chalk.gray(`· ${g.more} more`));
+    }
+    console.log();
+    const parts = [chalk.gray('newest first (by last activity)')];
+    if (hiddenProjects > 0)
+        parts.push(chalk.gray(`+${hiddenProjects} more project${hiddenProjects === 1 ? '' : 's'}`));
+    parts.push(chalk.gray('agents sessions --all spans every project on disk · <project> to drill in · --flat for the plain list'));
+    console.log(parts.join(chalk.gray('  ·  ')));
+    if (hiddenCount > 0)
+        console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+}
 function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
     if (tree) {
         // Group by directory; drop the id/version columns from view. The short id
@@ -823,10 +1103,12 @@ function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
         return;
     }
     // Only show the ticket column when at least one row carries a ref — otherwise
-    // it's a column of dashes that steals width from every topic.
+    // it's a column of dashes that steals width from every topic. The machine
+    // column (and its compact labels) is computed the same way the picker does it.
     const showTicket = sessions.some((s) => ticketLabel(s) !== '');
+    const cols = pickerColumnsFor(sessions);
     for (const session of sessions)
-        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket));
+        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket, cols));
     const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
     console.log(chalk.gray(`\n${countLine}`));
     if (hiddenCount > 0) {
@@ -983,28 +1265,115 @@ function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
     }
     return out + padding;
 }
-export function formatPickerLabel(s, query) {
+/** Fallback machine-column width when a pool-derived width isn't supplied.
+ * `pickerColumnsFor` normally computes `machineWidth` sized to the actual
+ * hostnames, floored/capped by these bounds so common ids like `yosemite-s0`
+ * (11) fit whole while a pathological hostname can't devour the topic column. */
+const PICKER_MACHINE_W = 11;
+const PICKER_MACHINE_MIN = 8;
+const PICKER_MACHINE_MAX = 18;
+/** Column width that shows every compacted hostname in `machines` whole (one
+ * trailing space for separation), bounded by MIN/MAX. */
+function machineColumnWidth(machines, label) {
+    const widest = machines.reduce((w, m) => Math.max(w, stringWidth(label(m))), 0);
+    return Math.min(PICKER_MACHINE_MAX, Math.max(PICKER_MACHINE_MIN, widest + 1));
+}
+/**
+ * Compact display form for machine ids: strip the longest shared dash-delimited
+ * prefix so "yosemite-s0"/"yosemite-s1" read as "s0"/"s1" while unrelated ids
+ * ("zion", "mac-mini") stay whole. Stripping a *common* prefix can't collide,
+ * and at least one segment is always kept.
+ */
+export function machineLabeler(machines) {
+    const uniq = [...new Set(machines.filter(Boolean))];
+    if (uniq.length < 2)
+        return (m) => m;
+    const parts = uniq.map((m) => m.split('-'));
+    const min = Math.min(...parts.map((p) => p.length));
+    let shared = 0;
+    while (shared < min - 1 && parts.every((p) => p[shared] === parts[0][shared]))
+        shared++;
+    if (shared === 0)
+        return (m) => m;
+    return (m) => {
+        const p = m.split('-');
+        return p.length > shared ? p.slice(shared).join('-') : m;
+    };
+}
+/**
+ * Column flags for a picker, computed once over the whole pool so every row
+ * aligns: the machine column only earns its width when the listing spans more
+ * than one box, the ticket column only when some row carries a PR/ticket ref.
+ */
+export function pickerColumnsFor(sessions) {
+    const machines = sessions.map((s) => s.machine).filter((m) => !!m);
+    const distinct = [...new Set(machines)];
+    const machineLabel = machineLabeler(machines);
+    return {
+        showMachine: distinct.length > 1,
+        machineLabel,
+        machineWidth: machineColumnWidth(distinct, machineLabel),
+        showTicket: sessions.some((s) => ticketLabel(s) !== ''),
+    };
+}
+export function formatPickerLabel(s, query, cols = {}) {
     const agentColor = colorAgent(s.agent);
-    const when = formatRelativeTime(s.timestamp);
+    const when = formatRelativeTime(s.lastActivity ?? s.timestamp);
     const project = s.project || '-';
     const tag = teamTag(s);
     const label = s.label;
     const topic = tag ? `${tag}${s.topic ?? ''}` : s.topic;
     const versionStr = s.version || '-';
+    const wt = s.worktreeSlug ? chalk.magenta(`wt:${s.worktreeSlug}`) : '';
+    const machineW = cols.machineWidth ?? PICKER_MACHINE_W;
+    const machineCell = cols.showMachine
+        ? chalk.gray(padRight(truncate((cols.machineLabel?.(s.machine ?? '') ?? s.machine ?? '') || '-', machineW - 1), machineW))
+        : '';
+    const TICKET_W = 10;
+    const ticketCell = cols.showTicket
+        ? chalk.blue(padRight(truncate(ticketLabel(s) || '-', TICKET_W), TICKET_W + 1))
+        : '';
+    // The picker prepends a gutter (cursor, plus a checkbox in multi-select mode);
+    // reserve it, plus the conditional columns, so the topic shrinks to fit and
+    // rows never wrap.
+    const gutter = cols.gutter ?? 2;
+    const machineColW = cols.showMachine ? machineW : 0;
+    const ticketW = cols.showTicket ? TICKET_W + 1 : 0;
+    const wtW = wt ? stringWidth(wt) + 1 : 0;
+    const topicW = Math.max(16, terminalWidth() - gutter - (10 + 9 + 8 + 16) - machineColW - ticketW - wtW - stringWidth(when) - 1);
     return (chalk.white(padRight(s.shortId, 10)) +
         agentColor(padRight(truncate(s.agent, 8), 9)) +
         chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
+        machineCell +
         chalk.cyan(padRight(truncate(project, 14), 16)) +
-        renderTopicCell(label, topic, query, 48, 50) +
+        renderTopicCell(label, topic, query, topicW, topicW) +
+        ticketCell +
+        (wt ? wt + ' ' : '') +
         chalk.gray(when));
 }
+/** Hints rotated above the picker so the flags/features stay discoverable. */
+const PICKER_TIPS = [
+    'Tip: narrow with -a/--agent (e.g. -a codex), or --project <name> for another folder.',
+    "Tip: --all searches every directory; -H/--host <machine> folds in another box's sessions.",
+    'Tip: just type to fuzzy-search prompts and responses; press space to preview a session.',
+    'Tip: --since 2d / --until <date> bound the time window; pass a session id to open it directly.',
+];
+/**
+ * Pick a hint to show above the picker. Deterministic (keys off the pool size)
+ * so it stays fixed across the picker's re-renders within a single run.
+ */
+export function formatPickerTip(sessions) {
+    return chalk.gray(PICKER_TIPS[sessions.length % PICKER_TIPS.length]);
+}
 export async function pickSessionInteractive(sessions, message = 'Search sessions:', initialSearch, hiddenCount = 0) {
     if (hiddenCount > 0) {
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
     }
+    const cols = pickerColumnsFor(sessions);
     try {
         return await sessionPicker({
             message,
+            subtitle: formatPickerTip(sessions),
             sessions,
             filter: (query) => {
                 // No query: show the full pool (picker viewport still paginates via pageSize).
@@ -1013,7 +1382,7 @@ export async function pickSessionInteractive(sessions, message = 'Search session
                     return sessions;
                 return filterSessionsByQuery(sessions, query);
             },
-            labelFor: (s, query) => formatPickerLabel(s, query),
+            labelFor: (s, query) => formatPickerLabel(s, query, cols),
             pageSize: PICKER_RECENT_COUNT,
             initialSearch,
         });
@@ -1024,7 +1393,41 @@ export async function pickSessionInteractive(sessions, message = 'Search session
         throw err;
     }
 }
+/**
+ * The machine a picked session lives on when its transcript is on that peer's
+ * disk (folded in over the live fan-out), else undefined. Keys off `_remote`,
+ * NOT `machine !== local`: a synced mirror is machine-tagged too, but its file
+ * is a local mirror path, so it must be read/resumed locally like any other.
+ */
+function remoteMachineOf(session) {
+    return session._remote ? session.machine : undefined;
+}
+/** True when the peer wasn't a dialable device; prints one clear line so a
+ * remote pick never dead-ends silently. */
+function warnNoPeerTarget(machine, session) {
+    console.log(chalk.yellow(`Session ${session.shortId} lives on ${machine}, which isn't a reachable device right now.`));
+    console.log(chalk.gray(`Register/wake it (ag devices), or run there: agents ssh ${machine}`));
+}
 async function handlePickedSession(picked) {
+    // A session on another machine is read/resumed ON that machine over SSH — its
+    // transcript and agent binary live there. Both actions execute on the peer
+    // (not a local `--host` hop, which would discover locally and dead-end for a
+    // session that exists only on the peer).
+    const remote = remoteMachineOf(picked.session);
+    if (remote) {
+        if (picked.action === 'view') {
+            const rc = await runOnPeer(['sessions', picked.session.shortId, '--markdown'], remote);
+            if (rc === 'no-target')
+                warnNoPeerTarget(remote, picked.session);
+        }
+        else {
+            console.log(chalk.gray(`Resuming ${picked.session.shortId} on ${remote} over SSH...`));
+            const rc = await runOnPeer(['sessions', 'resume', picked.session.shortId], remote, { tty: true });
+            if (rc === 'no-target')
+                warnNoPeerTarget(remote, picked.session);
+        }
+        return;
+    }
     if (picked.action === 'view') {
         await renderSession(picked.session, 'summary', {});
         return;
@@ -1049,26 +1452,49 @@ export async function resumeSessionInPlace(session) {
         return;
     }
     console.log(chalk.gray(`Resuming: ${resume.join(' ')} (cwd: ${cwd})`));
-    await new Promise((resolve) => {
-        const child = spawn(resume[0], resume.slice(1), {
-            cwd,
-            stdio: 'inherit',
-            shell: false,
-        });
+    // Resolve the (possibly version-pinned) launcher up front. On Windows the
+    // agent shim is a `.cmd`/`.ps1` and, under the shell needed to run it (see
+    // spawnResumeCommand), a missing command exits non-zero rather than emitting
+    // an ENOENT `error` event — so detect a removed version here instead of
+    // relying on that event, keeping the /continue fallback working on every OS.
+    if (!findExecutable(resume[0]) && session.version) {
+        const fallback = buildFallbackCommand(session);
+        if (fallback) {
+            console.log(chalk.gray(`Version ${session.version} is not installed. Falling back to current version via /continue...`));
+            await spawnResumeCommand(fallback, cwd);
+            return;
+        }
+    }
+    await spawnResumeCommand(resume, cwd);
+}
+/**
+ * Spawn a resume command as a foreground takeover (inherited stdio), resolving
+ * when it exits. On Windows the agent launcher is a `.cmd`/PATHEXT shim that
+ * `spawn` can't exec directly — a bare-name `shell:false` spawn throws
+ * `EFTYPE`/`ENOENT` there — so we go through the shell via `needsWindowsShell`.
+ * The spawn is guarded because such a failure can be thrown synchronously;
+ * without the guard it would surface under an unrelated "Failed to discover
+ * sessions" catch upstream instead of a truthful launch error.
+ */
+function spawnResumeCommand(cmd, cwd) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(cmd[0], cmd.slice(1), {
+                cwd,
+                stdio: 'inherit',
+                shell: needsWindowsShell(cmd[0]),
+            });
+        }
+        catch (err) {
+            console.error(chalk.red(`Failed to launch ${cmd[0]}: ${err.message}`));
+            resolve();
+            return;
+        }
         child.on('error', (err) => {
-            if (err.code === 'ENOENT' && session.version) {
-                const fallback = buildFallbackCommand(session);
-                if (fallback) {
-                    console.log(chalk.gray(`Version ${session.version} is not installed. Falling back to current version via /continue...`));
-                    const fb = spawn(fallback[0], fallback.slice(1), { cwd, stdio: 'inherit', shell: false });
-                    fb.on('error', (e) => { console.error(chalk.red(`Failed: ${e.message}`)); resolve(); });
-                    fb.on('close', () => resolve());
-                    return;
-                }
-            }
-            console.error(chalk.red(`Failed to launch ${resume[0]}: ${err.message}`));
+            console.error(chalk.red(`Failed to launch ${cmd[0]}: ${err.message}`));
             if (err.code === 'ENOENT') {
-                console.error(chalk.gray(`Make sure '${resume[0]}' is on your PATH.`));
+                console.error(chalk.gray(`Make sure '${cmd[0]}' is on your PATH.`));
             }
             resolve();
         });
@@ -1464,6 +1890,12 @@ export function registerSessionsCommands(program) {
         .argument('[query]', 'Session ID, search query, or path (., ../, /path) to filter by project')
         .description('Find, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
+        .option('--claude', 'Shorthand for --agent claude')
+        .option('--codex', 'Shorthand for --agent codex')
+        .option('--kimi', 'Shorthand for --agent kimi')
+        .option('--antigravity', 'Shorthand for --agent antigravity')
+        .option('--grok', 'Shorthand for --agent grok')
+        .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Include sessions from every directory (not just current project)')
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--project <name>', 'Filter by project name (searches across all directories)')
@@ -1481,12 +1913,14 @@ 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('--local', 'With --active: only this machine — skip the cross-machine SSH fan-out')
+        .option('--local', 'Only this machine — skip the cross-machine SSH fan-out (default listing and --active)')
         .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('--flat', 'Plain flat table (one row per session) instead of the grouped project overview')
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
         .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)');
+        .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)')
+        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command
@@ -1501,6 +1935,10 @@ export function registerSessionsCommands(program) {
       # Show only what's running right now (terminals, teams, cloud, headless)
       agents sessions --active
 
+      # The interactive list folds in other online machines automatically,
+      # labelled by host with this machine first. Stay local with --local:
+      agents sessions --local
+
       # Search across every directory, not just this project
       agents sessions "topic" --all
 
@@ -1514,6 +1952,7 @@ export function registerSessionsCommands(program) {
       agents sessions --all "deploy script" --host box-a --host box-b
     `,
         notes: `
+      - The interactive listing folds in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; --json and single-id lookups stay local.
       - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --include and --exclude are mutually exclusive.
       - --first and --last are mutually exclusive.
@@ -1528,6 +1967,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
+    registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();