@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/dist/commands/sessions.js

@@ -17,6 +17,8 @@ import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
 import { looksLikePath, toComparablePath, homeDir } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
+import { machineId, normalizeHost } from '../lib/session/sync/config.js';
+import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
@@ -33,6 +35,7 @@ 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';
 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'];
@@ -194,6 +197,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 +358,148 @@ 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;
+}
+/** 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 +511,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 +540,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) {
@@ -533,7 +690,8 @@ async function sessionsAction(query, options) {
         }
         // Non-interactive fallback (piped output)
         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 +718,82 @@ 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) {
     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}`) : '';
+    const TICKET_W = 10;
+    const ticketCell = showTicket
+        ? chalk.blue(padToWidth(truncateToWidth(ticketLabel(session) || '-', TICKET_W), TICKET_W + 1))
+        : '';
+    const glyphW = glyph ? 2 : 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);
     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)) +
         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;
+    }
+}
+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 +814,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 +822,11 @@ 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.
+    const showTicket = sessions.some((s) => ticketLabel(s) !== '');
     for (const session of sessions)
-        console.log(flatSessionRow(session));
+        console.log(flatSessionRow(session, liveIndex?.get(session.id), showTicket));
     const countLine = `${sessions.length} session${sessions.length === 1 ? '' : 's'}.`;
     console.log(chalk.gray(`\n${countLine}`));
     if (hiddenCount > 0) {
@@ -677,6 +875,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 +983,7 @@ function renderTopicCell(label, topic, query, visibleWidth, paddedWidth) {
     }
     return out + padding;
 }
-function formatPickerLabel(s, query) {
+export function formatPickerLabel(s, query) {
     const agentColor = colorAgent(s.agent);
     const when = formatRelativeTime(s.timestamp);
     const project = s.project || '-';
@@ -823,13 +1029,23 @@ async function handlePickedSession(picked) {
         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})`));
@@ -840,10 +1056,10 @@ async function handlePickedSession(picked) {
             shell: false,
         });
         child.on('error', (err) => {
-            if (err.code === 'ENOENT' && picked.session.version) {
-                const fallback = buildFallbackCommand(picked.session);
+            if (err.code === 'ENOENT' && session.version) {
+                const fallback = buildFallbackCommand(session);
                 if (fallback) {
-                    console.log(chalk.gray(`Version ${picked.session.version} is not installed. Falling back to current version via /continue...`));
+                    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());
@@ -883,6 +1099,7 @@ export function buildResumeCommand(session) {
         case 'opencode':
             return ['opencode', '--session', session.id];
         case 'gemini':
+        case 'antigravity':
         case 'openclaw':
         case 'rush':
         case 'hermes':
@@ -971,7 +1188,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 +1481,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('--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('--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, {
@@ -1308,6 +1527,7 @@ export function registerSessionsCommands(program) {
     });
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsSyncCommand(sessionsCmd);
+    registerSessionsResumeCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/status.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents status` — the unified sync-status surface.
+ *
+ * One command that answers "is my fleet in sync?" the same way every other
+ * surface does, because it reads the same engine (computeSyncStatus). Human mode
+ * renders the summary and, when a TTY finds drift, offers the interactive
+ * "sync now?" flow (promptDriftSync). `--json` emits the stable UnifiedSyncStatus
+ * contract the menu-bar and Agency consume. `--yes` reconciles everything with no
+ * prompts (the "kick it" path, safe in scripts).
+ */
+import { Command } from 'commander';
+export declare function registerStatusCommand(program: Command): void;

package/dist/commands/status.js

@@ -0,0 +1,81 @@
+/**
+ * `agents status` — the unified sync-status surface.
+ *
+ * One command that answers "is my fleet in sync?" the same way every other
+ * surface does, because it reads the same engine (computeSyncStatus). Human mode
+ * renders the summary and, when a TTY finds drift, offers the interactive
+ * "sync now?" flow (promptDriftSync). `--json` emits the stable UnifiedSyncStatus
+ * contract the menu-bar and Agency consume. `--yes` reconciles everything with no
+ * prompts (the "kick it" path, safe in scripts).
+ */
+import chalk from 'chalk';
+import { AGENTS } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { computeSyncStatus } from '../lib/sync-status.js';
+import { promptDriftSync } from '../lib/drift-sync.js';
+const agentName = (id) => AGENTS[id]?.name ?? id;
+function versionSummary(v) {
+    if (!v.everSynced)
+        return chalk.gray('never synced');
+    if (v.needsSync) {
+        const bits = [];
+        if (v.counts.drifted)
+            bits.push(`${v.counts.drifted} drifted`);
+        if (v.counts.missing)
+            bits.push(`${v.counts.missing} missing`);
+        return chalk.yellow(bits.join(' · '));
+    }
+    return chalk.green('in sync');
+}
+export function registerStatusCommand(program) {
+    const cmd = program
+        .command('status')
+        .description('Unified sync status across the fleet — what is drifted, missing, or behind, with an option to sync it.')
+        .option('--json', 'Output the machine-readable UnifiedSyncStatus contract')
+        .option('--yes', 'Reconcile everything detected (pull .system if behind + sync drifted/missing resources) without prompting')
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+    setHelpSections(cmd, {
+        examples: `
+      # Show what's out of sync; offer to fix it (interactive)
+      agents status
+
+      # Machine-readable status for the menu-bar / Agency
+      agents status --json
+
+      # Reconcile everything with no prompts (CI / scripts / the "kick it" path)
+      agents status --yes
+    `,
+    });
+    cmd.action(async (opts) => {
+        const cwd = opts.cwd ?? process.cwd();
+        if (opts.json) {
+            const status = await computeSyncStatus({ cwd });
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        const status = await computeSyncStatus({ cwd });
+        // Human summary header (always) — the per-version readout.
+        console.log(chalk.bold('Fleet sync status'));
+        if (status.system.unknown) {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.gray('freshness unknown (no upstream)')}`);
+        }
+        else if (status.system.behind > 0) {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.yellow(`${status.system.behind} behind`)}`);
+        }
+        else {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.green('up to date')}`);
+        }
+        if (status.agents.length === 0) {
+            console.log(chalk.gray('  (no installed agent versions)'));
+        }
+        for (const v of status.agents) {
+            const label = `${agentName(v.agent)}@${v.version}${v.isDefault ? chalk.gray(' (default)') : ''}`;
+            console.log(`  ${label.padEnd(28)} ${versionSummary(v)}`);
+        }
+        if (status.totals.orphan > 0) {
+            console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
+        }
+        // Hand off to the shared interactive/apply flow (summary already printed above).
+        await promptDriftSync({ cwd, yes: opts.yes, status, quiet: true });
+    });
+}