@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/sessions.js

@@ -15,13 +15,16 @@ 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 { machineId, normalizeHost } from '../lib/session/sync/config.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';
@@ -33,6 +36,8 @@ import { sessionPicker } from './sessions-picker.js';
 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`;
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
 const LOAD_VERBS = ['Loading', 'Scanning', 'Gathering', 'Indexing', 'Reading'];
@@ -75,6 +80,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.
  */
@@ -194,6 +205,43 @@ function activityLabel(s) {
         return 'idle';
     return s.status === 'input_required' ? 'waiting' : s.status;
 }
+/**
+ * Index live sessions by their full session UUID so a historical `SessionMeta`
+ * row (`meta.id`) can be matched to the session that is still running now.
+ * Rows without a sessionId (some cloud/headless probes) are skipped — they
+ * can't be correlated back to a transcript on disk.
+ */
+export function indexActiveBySessionId(active) {
+    const byId = new Map();
+    for (const a of active) {
+        if (a.sessionId)
+            byId.set(a.sessionId, a);
+    }
+    return byId;
+}
+/**
+ * The live decoration for a listing row: a status glyph and the latest-turn
+ * preview, when the session is still running. `●` running / `◐` waiting on the
+ * user / `○` idle, colored by the same `statusColor` the --active view uses.
+ * Returns empty strings when there is no live match, so callers render the
+ * plain historical row unchanged.
+ */
+export function liveGlyphAndPreview(a) {
+    if (!a)
+        return { glyph: '', preview: '' };
+    const waiting = a.status === 'input_required' || a.activity === 'waiting_input';
+    const running = a.status === 'running' || a.activity === 'working';
+    const shape = waiting ? '◐' : running ? '●' : '○';
+    return { glyph: statusColor(a.status)(shape), preview: buildSessionDescription(a) };
+}
+/**
+ * The tracker/PR ref for a session's dedicated column: the ticket id when known,
+ * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
+ * into a scannable column instead of jamming against a truncated topic.
+ */
+export function ticketLabel(s) {
+    return s.ticketId ?? (s.prNumber ? `PR#${s.prNumber}` : '');
+}
 /**
  * Compact, colour-coded badges for the durable/awaiting signals. Text-only (no
  * emoji, per repo convention): `plan` / `ask` / `perm` for why it's waiting,
@@ -318,48 +366,183 @@ export function groupActiveSessions(sessions) {
     });
     return { workspaces };
 }
-/** Render the unified active-session view. */
-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(waitingOnly ? 'No sessions waiting on input.' : 'No active agent sessions.'));
-        return;
+/**
+ * The machine a session belongs to: an explicit tag (set when merging
+ * cross-machine results) wins; else the process's provenance host (normalized
+ * to the same id form); else the local machine. Never keys off `ActiveSession.host`
+ * — that is the terminal *app* (code/tmux), not the computer.
+ */
+function machineKeyFor(s, localMachine) {
+    if (s.machine)
+        return s.machine;
+    if (s.provenance?.host)
+        return normalizeHost(s.provenance.host);
+    return localMachine;
+}
+/**
+ * Group active sessions by machine, then delegate each machine's sessions to the
+ * existing workspace/window grouping. Local machine is pinned first and flagged;
+ * the rest sort by session count descending, then name. Pure — `localMachine` is
+ * injected so the function stays testable without reading os.hostname().
+ */
+export function groupSessionsByMachine(sessions, localMachine) {
+    const byMachine = new Map();
+    for (const s of sessions) {
+        const key = machineKeyFor(s, localMachine);
+        (byMachine.get(key) ?? byMachine.set(key, []).get(key)).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);
+    });
+    const machines = keys.map((machine) => ({
+        machine,
+        isLocal: machine === localMachine,
+        total: byMachine.get(machine).length,
+        layout: groupActiveSessions(byMachine.get(machine)),
+    }));
+    return { machines };
+}
+/**
+ * Collapse duplicate sessions after a cross-machine merge. Two rows collapse
+ * only when they share both machine and session UUID (the same host listed
+ * twice, or a local/remote overlap); rows without a sessionId can't be
+ * correlated, so they're all kept.
+ */
+export function dedupeByMachineSession(sessions) {
+    const seen = new Set();
+    const out = [];
+    for (const s of sessions) {
+        if (!s.sessionId) {
+            out.push(s);
+            continue;
+        }
+        const key = `${s.machine ?? ''}:${s.sessionId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(s);
     }
-    const layout = groupActiveSessions(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));
+}
+/** Print one machine's workspace tree, indented under its machine header. */
+function renderWorkspaceLayout(layout, base) {
     let first = true;
     for (const ws of layout.workspaces) {
         if (!first)
             console.log();
         first = false;
-        // Print workspace header
         const header = ws.key === '__cloud__'
             ? chalk.magenta.bold('cloud')
             : ws.key === '__unknown__'
                 ? chalk.gray.bold('unknown')
                 : chalk.cyan.bold(shortCwd(ws.key));
-        console.log(`${header} ${chalk.gray(`(${ws.total})`)}`);
+        console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}`);
         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.
             const host = win.sessions.find((s) => s.host)?.host ?? 'terminal';
             const winHeader = `${chalk.gray(host)} ${chalk.gray('·')} ${chalk.gray(shortWindowLabel(win.windowId))} ${chalk.gray(`(${win.sessions.length})`)}`;
-            console.log('  ' + winHeader);
+            console.log(base + '  ' + winHeader);
             for (const s of win.sessions)
-                printActiveRow(s, '    ');
+                printActiveRow(s, base + '    ');
         }
         for (const s of ws.flat)
-            printActiveRow(s, '  ');
+            printActiveRow(s, base + '  ');
+    }
+}
+/** Machine header: `▸ <name> ← this machine` for the local box (cyan), matching
+ * the `ag devices list` treatment; a plain `▸ <name>` for remotes. */
+function printMachineHeader(mg) {
+    const marker = mg.isLocal ? chalk.cyan('▸ ') : chalk.gray('▸ ');
+    const name = mg.isLocal ? chalk.bold.cyan(mg.machine) : chalk.bold(mg.machine);
+    const here = mg.isLocal ? chalk.cyan('  ← this machine') : '';
+    console.log(`${marker}${name} ${chalk.gray(`(${mg.total})`)}${here}`);
+}
+/**
+ * Render the unified active-session view, grouped by machine. Local sessions
+ * come from `getActiveSessions()`; unless `--local`, sessions from other
+ * machines are folded in over SSH (explicit `--host` targets, else the
+ * registered online devices from `ag devices`). A tip is shown when there are
+ * no other machines to include.
+ */
+async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
+    const self = machineId();
+    const local = await getActiveSessions();
+    for (const s of local)
+        if (!s.machine)
+            s.machine = self;
+    let remoteDeviceCount = 0;
+    let merged = local;
+    if (!opts.local) {
+        const remote = await gatherRemoteActive(opts.hosts);
+        remoteDeviceCount = remote.deviceCount;
+        merged = dedupeByMachineSession([...local, ...remote.sessions]);
+    }
+    // --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 ? merged.filter(s => s.status === 'input_required') : merged;
+    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(waitingOnly ? 'No sessions waiting on input.' : 'No active agent sessions.'));
+        if (!opts.local && !opts.hosts?.length && remoteDeviceCount === 0)
+            printCrossMachineTip();
+        return;
+    }
+    const grouped = groupSessionsByMachine(sessions, self);
+    let firstMachine = true;
+    for (const mg of grouped.machines) {
+        if (!firstMachine)
+            console.log();
+        firstMachine = false;
+        printMachineHeader(mg);
+        renderWorkspaceLayout(mg.layout, '  ');
     }
     const runningCount = sessions.filter(s => s.status === 'running').length;
     const idleCount = sessions.filter(s => s.status === 'idle').length;
@@ -371,14 +554,25 @@ async function renderActiveSessions(asJson, waitingOnly = false) {
         parts.push(`${idleCount} idle`);
     if (queuedCount > 0)
         parts.push(`${queuedCount} queued`);
-    console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}).`));
+    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.
+    if (!opts.local && !opts.hosts?.length && remoteDeviceCount === 0)
+        printCrossMachineTip();
     // Scriptable gate: a non-zero exit when anything is waiting on the user.
     if (waitingOnly && sessions.length > 0)
         process.exitCode = 1;
 }
+/** Nudge shown when `--active` has no other machines to fold in. */
+function printCrossMachineTip() {
+    console.log(chalk.gray("\nTip: include sessions from your other machines — register them with 'ag devices sync', then rerun. Use --local to skip."));
+}
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
-    if (options.host && options.host.length > 0) {
+    // --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).
+    if (options.host && options.host.length > 0 && !options.active) {
         try {
             runRemoteSessions(options.host);
         }
@@ -389,7 +583,13 @@ async function sessionsAction(query, options) {
         return;
     }
     if (options.active) {
-        await renderActiveSessions(options.json === true, options.waiting === true);
+        // AGENTS_SESSIONS_LOCAL is set by a parent fan-out invocation (see
+        // remote-active.ts) so a peer answers for itself without recursing.
+        const forceLocal = options.local === true || process.env.AGENTS_SESSIONS_LOCAL === '1';
+        await renderActiveSessions(options.json === true, options.waiting === true, {
+            local: forceLocal,
+            hosts: options.host,
+        });
         return;
     }
     if (options.cloud) {
@@ -442,8 +642,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 {
@@ -456,7 +666,7 @@ async function sessionsAction(query, options) {
         const scope = {
             agent,
             version,
-            all: pathFilter ? undefined : options.all,
+            all: pathFilter ? undefined : (wantsOverview ? true : options.all),
             cwd: process.cwd(),
             cwdPrefix: pathFilter,
             project: options.project,
@@ -500,12 +710,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}.`));
@@ -518,9 +758,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);
@@ -531,9 +781,10 @@ 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;
-        printSessionTable(filtered, hiddenCount, options.tree === true);
+        const liveIndex = await maybeLiveIndex(options);
+        printSessionTable(filtered, hiddenCount, options.tree === true, liveIndex);
     }
     catch (err) {
         tracker.stop();
@@ -560,45 +811,164 @@ function metaSignals(s) {
         ticket: s.ticketId ? { id: s.ticketId } : undefined,
     };
 }
-/** One flat table row: shortId · agent · version · project · topic(+badges) · time. */
-function flatSessionRow(session) {
+/** One flat table row:
+ *   shortId · agent · version · project · [glyph] label·doing · [ticket] · [wt] · time
+ * `doing` is the live preview when running, else the topic. The `ticket` column
+ * (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, cols = {}) {
     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);
+    const { glyph, preview } = liveGlyphAndPreview(live);
+    // A running session's live preview says what the agent is doing now; a
+    // 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 - 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(versionStr, 7), 8)) +
+        chalk.yellow(padToWidth(truncateToWidth(session.version || '-', 7), 8)) +
+        machineCell +
         chalk.cyan(padToWidth(truncateToWidth(project, 14), 16)) +
-        renderTopicCell(label, topic, '', topicW, topicW) +
-        (badges ? badges + ' ' : '') +
+        (glyph ? glyph + ' ' : '') +
+        renderTopicCell(label, doing, '', topicW, topicW) +
+        ticketCell +
+        (wt ? wt + ' ' : '') +
         chalk.gray(when));
 }
 /** One tree-mode row (grouped under a dir header): id · agent · badges · topic · time. No version/project column. */
-function treeSessionRow(session) {
+function treeSessionRow(session, live) {
     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 { glyph, preview } = liveGlyphAndPreview(live);
+    const topic = (preview || (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);
+    const glyphW = glyph ? 2 : 0;
+    const topicW = Math.max(12, terminalWidth() - (2 + 9 + 8) - glyphW - badgeW - stringWidth(when) - 1);
     return ('  ' +
         chalk.dim(padToWidth(session.shortId, 9)) +
         agentColor(padToWidth(truncateToWidth(session.agent, 7), 8)) +
         (badges ? badges + ' ' : '') +
+        (glyph ? glyph + ' ' : '') +
         padToWidth(chalk.white(truncateToWidth(head, topicW)), topicW) +
         ' ' + chalk.gray(when));
 }
-function printSessionTable(sessions, hiddenCount = 0, tree = false) {
+/**
+ * Live-session index for enriching the default listing, or undefined when
+ * enrichment is off (`--no-live`) or irrelevant (`--json`, which serializes
+ * SessionMeta). Full detection (incl. the headless `ps` scan) is deliberate:
+ * bare-CLI and tmux agents are the common case here, and skipping them would
+ * leave the glyph almost never showing. The listing is a one-shot user action,
+ * not a hot loop, so the `ps`/`lsof` cost is acceptable; `--no-live` is the
+ * escape hatch. Never throws — a probe failure just yields a plain listing.
+ */
+async function maybeLiveIndex(options) {
+    if (options.live === false || options.json)
+        return undefined;
+    try {
+        return indexActiveBySessionId(await getActiveSessions());
+    }
+    catch {
+        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].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')];
+    if (hiddenProjects > 0)
+        parts.push(chalk.gray(`+${hiddenProjects} more project${hiddenProjects === 1 ? '' : 's'} · agents sessions --all`));
+    parts.push(chalk.gray('agents sessions <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
         // stays as each row's leading handle (the address to read/resume it).
@@ -619,7 +989,7 @@ function printSessionTable(sessions, hiddenCount = 0, tree = 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));
+                console.log(treeSessionRow(s, liveIndex?.get(s.id)));
         }
         const dirWord = keys.length === 1 ? 'directory' : 'directories';
         console.log(chalk.gray(`\n${sessions.length} session${sessions.length === 1 ? '' : 's'} across ${keys.length} ${dirWord}.`));
@@ -627,8 +997,13 @@ function printSessionTable(sessions, hiddenCount = 0, tree = false) {
             console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
         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. 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));
+        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) {
@@ -677,6 +1052,14 @@ function resolveViewMode(options, filters) {
         return 'markdown';
     return 'summary';
 }
+/**
+ * Render a session's full transcript to stdout — the non-follow view behind
+ * `agents logs <sessionId>`. Reuses the same markdown renderer as
+ * `agents sessions <id> --markdown`.
+ */
+export async function renderSessionLog(session) {
+    await renderSession(session, 'markdown', {});
+}
 async function renderSession(session, mode, filters, options = {}) {
     // OpenCode stores sessions in SQLite; filePath is "db_path#session_id"
     const realPath = session.filePath.split('#')[0];
@@ -777,7 +1160,58 @@ function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
     }
     return out + padding;
 }
-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 project = s.project || '-';
@@ -785,20 +1219,56 @@ function formatPickerLabel(s, query) {
     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).
@@ -807,7 +1277,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,
         });
@@ -818,41 +1288,108 @@ 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;
     }
-    const cwd = picked.session.cwd && fs.existsSync(picked.session.cwd)
-        ? picked.session.cwd
+    await resumeSessionInPlace(picked.session);
+}
+/**
+ * Resume a session in the current terminal — a foreground takeover of this
+ * process. Used by the single-select picker and by `sessions resume` when the
+ * chosen destination is "in place" (unknown emulator / off-macOS, single pick).
+ * Falls back to the current version via `/continue` when the version-pinned
+ * binary is missing (ENOENT).
+ */
+export async function resumeSessionInPlace(session) {
+    const cwd = session.cwd && fs.existsSync(session.cwd)
+        ? session.cwd
         : process.cwd();
-    const resume = buildResumeCommand(picked.session);
+    const resume = buildResumeCommand(session);
     if (!resume) {
-        console.log(chalk.yellow(`Resume is not supported for ${picked.session.agent} sessions yet. Showing summary instead.`));
-        await renderSession(picked.session, 'summary', {});
+        console.log(chalk.yellow(`Resume is not supported for ${session.agent} sessions yet. Showing summary instead.`));
+        await renderSession(session, 'summary', {});
         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' && picked.session.version) {
-                const fallback = buildFallbackCommand(picked.session);
-                if (fallback) {
-                    console.log(chalk.gray(`Version ${picked.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();
         });
@@ -883,6 +1420,7 @@ export function buildResumeCommand(session) {
         case 'opencode':
             return ['opencode', '--session', session.id];
         case 'gemini':
+        case 'antigravity':
         case 'openclaw':
         case 'rush':
         case 'hermes':
@@ -971,7 +1509,7 @@ async function runCloudSessions(query, options) {
     // Ensure the SessionMeta points at the local cache path for renderSession.
     await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts, options);
 }
-function parseAgentFilter(agentName) {
+export function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
     const [name, version] = agentName.split('@', 2);
@@ -1264,8 +1802,11 @@ 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', '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)');
     setHelpSections(sessionsCmd, {
@@ -1282,6 +1823,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
 
@@ -1295,6 +1840,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.
@@ -1308,6 +1854,8 @@ export function registerSessionsCommands(program) {
     });
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsSyncCommand(sessionsCmd);
+    registerSessionsResumeCommand(sessionsCmd);
+    registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();