@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/commands/sessions.js

@@ -15,15 +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 } 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,6 +37,7 @@ 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'];
@@ -78,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.
  */
@@ -423,6 +431,41 @@ 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));
+}
 /** Print one machine's workspace tree, indented under its machine header. */
 function renderWorkspaceLayout(layout, base) {
     let first = true;
@@ -599,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 {
@@ -613,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,
@@ -657,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}.`));
@@ -675,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);
@@ -688,7 +781,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,7 +817,7 @@ 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 project = session.project || '-';
@@ -735,17 +828,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) +
@@ -793,6 +895,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].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
@@ -823,10 +998,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,7 +1160,58 @@ 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 project = s.project || '-';
@@ -991,20 +1219,56 @@ export 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).
@@ -1013,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,
         });
@@ -1024,7 +1288,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 +1347,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();
         });
@@ -1481,9 +1802,10 @@ 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)');
@@ -1501,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
 
@@ -1514,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.
@@ -1528,6 +1855,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
+    registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/setup.js

@@ -76,9 +76,11 @@ export async function runSetup(program, options = {}) {
         console.log(chalk.gray(`Populate ~/.agents/.system/ yourself before running other commands that depend on it.\n`));
     }
     else {
-        console.log(chalk.gray(`Cloning the system repo from ${systemRepoSlug(systemRepo)} into ~/.agents/.system/.\n`));
+        console.log(chalk.gray(alreadyConfigured
+            ? `Updating the system repo from ${systemRepoSlug(systemRepo)} in ~/.agents/.system/.\n`
+            : `Cloning the system repo from ${systemRepoSlug(systemRepo)} into ~/.agents/.system/.\n`));
         ensureAgentsDir();
-        const spinner = ora('Cloning system repo...').start();
+        const spinner = ora(alreadyConfigured ? 'Updating system repo...' : 'Cloning system repo...').start();
         if (isGitRepo(agentsDir)) {
             // --force on an existing repo: pull instead of re-clone
             const result = await pullRepo(agentsDir);

package/dist/commands/sync.d.ts

@@ -2,10 +2,12 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync                                         # umbrella: fetch remote (repos+secrets+sessions) -> reconcile all
+ *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets/sessions opt-in)
  *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
  *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
  *   agents sync --local                                 # umbrella: reconcile all, no fetch
+ *   agents sync system                                  # one repo: git pull --rebase (pull-only mirror)
+ *   agents sync user                                    # one repo: git pull --rebase + push
  *   agents sync claude                                  # one agent: uses default/sole installed version
  *   agents sync claude@2.1.142                          # one agent: explicit version
  *   agents sync claude@latest                           # one agent: newest installed