@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/sessions-inject.js

@@ -0,0 +1,111 @@
+/**
+ * `agents sessions inject <sessionId> <text>` — deliver text into the terminal a
+ * running session lives in. The CLI face of the Terminal Engine's Gap 2 primitive
+ * (`injectIntoTerminal`, src/lib/terminal/inject.ts), so a native watchdog
+ * (RUSH-1415) can shell out to nudge a stalled agent with "continue".
+ *
+ * Resolution: find the active session by id, map its `provenance.reply` rail
+ * (provenance.ts:47) to an engine `InjectTarget` and inject. Today only tmux rails
+ * are externally addressable; `--pane`/`--pty` target a backend directly when the
+ * handle is already known (skipping the session lookup).
+ */
+import chalk from 'chalk';
+import { getActiveSessions } from '../lib/session/active.js';
+import { injectTargetFromReplyRail } from '../lib/session/inject.js';
+import { injectIntoTerminal } from '../lib/terminal/index.js';
+import { setHelpSections } from '../lib/help.js';
+/** Resolve a session id (short or full) to an addressable terminal target. */
+async function resolveTarget(sessionId) {
+    const sessions = await getActiveSessions();
+    const match = sessions.find((s) => s.sessionId === sessionId || (s.sessionId != null && s.sessionId.startsWith(sessionId)));
+    if (!match)
+        return { target: null, reason: `No active session matches "${sessionId}".` };
+    const rail = match.provenance?.reply;
+    if (!rail) {
+        return {
+            target: null,
+            reason: `Session "${sessionId}" has no addressable reply rail (not running under tmux). Relaunch it under a tmux/pty rail to inject.`,
+        };
+    }
+    const target = injectTargetFromReplyRail(rail);
+    if (!target)
+        return { target: null, reason: `Session "${sessionId}" reply rail is not injectable.` };
+    return { target };
+}
+async function runInject(sessionId, text, options) {
+    // Direct-target shortcuts skip the session lookup — the watchdog often already
+    // holds the pane id or pty session it wants to type into.
+    let target = null;
+    if (options.pty) {
+        target = { backend: 'pty', id: options.pty };
+    }
+    else if (options.pane) {
+        target = { backend: 'tmux', pane: options.pane, socket: options.socket };
+    }
+    else {
+        const resolved = await resolveTarget(sessionId);
+        if (!resolved.target) {
+            if (options.json)
+                console.log(JSON.stringify({ ok: false, error: resolved.reason }));
+            else
+                console.error(chalk.red(resolved.reason));
+            process.exit(1);
+        }
+        target = resolved.target;
+    }
+    const res = await injectIntoTerminal(target, text, {
+        enter: options.enter !== false,
+        combined: options.combined,
+        socket: options.socket,
+        host: options.host,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(res));
+    }
+    else if (res.ok) {
+        console.log(chalk.green(`Injected into ${res.backend} (${res.writes} write${res.writes === 1 ? '' : 's'}).`));
+    }
+    else {
+        console.error(chalk.red(res.error ?? 'injection failed'));
+    }
+    if (!res.ok)
+        process.exit(1);
+}
+/** Attach the `inject` subcommand to an existing `sessions` command. */
+export function registerSessionsInjectCommand(sessionsCmd) {
+    const injectCmd = sessionsCmd
+        .command('inject <sessionId> <text>')
+        .description('Deliver text (+ Enter) into the terminal a running session lives in — nudge a stalled agent.')
+        .option('--pane <id>', 'Target a tmux pane id directly (e.g. %3), skipping session lookup')
+        .option('--pty <id>', 'Target an agents-pty session id directly, skipping session lookup')
+        .option('--socket <path>', 'tmux socket path (defaults to the session/shared socket)')
+        .option('--host <target>', 'Deliver on a remote host over SSH (tmux/AppleScript backends)')
+        .option('--no-enter', 'Send only the text, without a trailing Enter')
+        .option('--combined', 'Fuse text + Enter into ONE write (default: two writes, Ink-TUI safe)')
+        .option('--json', 'Output the InjectResult as JSON');
+    setHelpSections(injectCmd, {
+        examples: `
+      # Nudge a stalled agent by session id (resolves its tmux pane)
+      agents sessions inject a1b2c3d4 "continue"
+
+      # Target a tmux pane directly (what a watchdog already holds)
+      agents sessions inject _ "continue" --pane %3 --socket /tmp/agents/tmux.sock
+
+      # Type into an agents-pty session without submitting
+      agents sessions inject _ "ls" --pty $SID --no-enter
+    `,
+        notes: `
+      - Ink-TUI Enter semantics: by default the text and Enter are two separate
+        writes, which is what Claude's Ink TUI needs. --combined fuses them.
+      - Only sessions running under a tmux pane are addressable by id today
+        (provenance.ts reply rails). Use --pane/--pty for direct targeting.
+      - Built on the Terminal Engine (src/lib/terminal): --host runs the tmux /
+        AppleScript spec over the same SSH transport the launch engine uses.
+    `,
+    });
+    // The parent `sessions` command also defines --json, so it binds there;
+    // optsWithGlobals() merges parent + subcommand options so --json is honored.
+    injectCmd.action(async (sessionId, text, _options, command) => {
+        await runInject(sessionId, text, command.optsWithGlobals());
+    });
+}

package/dist/commands/sessions-picker.d.ts

@@ -5,6 +5,8 @@ export interface PickedSession {
 }
 export interface SessionPickerConfig {
     message: string;
+    /** Dim hint line shown under the header (filters/flags tip). */
+    subtitle?: string;
     sessions: SessionMeta[];
     filter: (query: string) => SessionMeta[];
     labelFor: (s: SessionMeta, query: string) => string;

package/dist/commands/sessions-picker.js

@@ -12,6 +12,14 @@ import { linkPath, relativeToCwd } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
+/** A session whose transcript lives on another machine (folded in over the live
+ * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
+ * can't parse it locally — it shows metadata + a "resume there" note instead.
+ * Keys off `_remote`, not the machine tag, so locally-readable synced mirrors
+ * still parse their file normally. */
+function remoteMachineOf(session) {
+    return session._remote ? session.machine : undefined;
+}
 /**
  * SessionMeta originates in discover.ts (gitBranch, cwd, label, etc. read from
  * untrusted session files). parseSession sanitizes event payloads at its
@@ -37,9 +45,22 @@ function sanitizeMeta(s) {
 const previewCache = new Map();
 /** Build a cached multi-line preview string for display in the session picker. */
 export function buildPreview(session) {
-    const cached = previewCache.get(session.id);
+    const remote = remoteMachineOf(session);
+    const cacheKey = remote ? `${remote}:${session.id}` : session.id;
+    const cached = previewCache.get(cacheKey);
     if (cached)
         return cached;
+    const safe = sanitizeMeta(session);
+    // Remote session: the transcript is on the peer's disk, so there is nothing to
+    // parse here. Show the metadata header (agent, cwd, msgs, tokens — all carried
+    // over in the fan-out) plus where it lives and how to open it.
+    if (remote) {
+        const note = '  ' + chalk.gray(`on `) + chalk.bold.white(remote)
+            + chalk.gray(` — enter to resume there, or space then enter to read it over SSH`);
+        const output = [formatHeader(safe, []), '', note].join('\n');
+        previewCache.set(cacheKey, output);
+        return output;
+    }
     let events = [];
     let parseError;
     try {
@@ -48,13 +69,12 @@ export function buildPreview(session) {
     catch (err) {
         parseError = sanitizeForTerminal(err?.message ?? String(err));
     }
-    const safe = sanitizeMeta(session);
     const header = formatHeader(safe, events);
     const body = parseError
         ? '  ' + chalk.red(`Failed to parse session: ${parseError}`)
         : formatCompactPreview(events, safe);
     const output = [header, '', body].filter(Boolean).join('\n');
-    previewCache.set(session.id, output);
+    previewCache.set(cacheKey, output);
     return output;
 }
 function displayAgent(agent) {
@@ -342,6 +362,7 @@ function truncate(s, max) {
 export async function sessionPicker(config) {
     const picked = await itemPicker({
         message: config.message,
+        subtitle: config.subtitle,
         items: config.sessions,
         filter: config.filter,
         labelFor: config.labelFor,

package/dist/commands/sessions-resume.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-resume.js

@@ -0,0 +1,221 @@
+/**
+ * `agents sessions resume` — multi-select sessions and fan each one out into a
+ * terminal surface via the terminal launch engine (src/lib/terminal).
+ *
+ * Unlike the single-select picker behind bare `agents sessions` (which resumes
+ * one session in place), this opens a checkbox picker, then asks where the
+ * chosen sessions should resume. By default they pack two-per-tab (session 1 in
+ * a new tab, session 2 split beside it, session 3 a new tab, …) in the terminal
+ * you're in — iTerm / Ghostty / tmux, locally or on a remote host via --host.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { discoverSessions } from '../lib/session/discover.js';
+import { filterTeamSessions } from '../lib/session/team-filter.js';
+import { multiItemPicker, itemPicker } from '../lib/picker.js';
+import { buildPreview } from './sessions-picker.js';
+import { filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, buildResumeCommand, resumeSessionInPlace, parseAgentFilter, } from './sessions.js';
+import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, } from '../lib/terminal/index.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { setHelpSections } from '../lib/help.js';
+import { confirm } from '@inquirer/prompts';
+/** Opening more than this many live sessions at once asks for confirmation first. */
+const CONFIRM_THRESHOLD = 5;
+export function registerSessionsResumeCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('resume')
+        .argument('[query]', 'Filter sessions before selecting (topic, path, or id fragment)')
+        .description('Multi-select sessions and resume each in a terminal tab/split (this terminal, iTerm, Ghostty, tmux, VSCodium; local or --host).')
+        .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
+        .option('--all', 'Include sessions from every directory (not just current project)')
+        .option('--teams', 'Include team-spawned sessions (hidden by default)')
+        .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
+        .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
+        .option('--host <alias>', 'Resume on a remote host over SSH (defaults to tmux there)')
+        .option('--iterm', 'Force the iTerm backend')
+        .option('--ghostty', 'Force the Ghostty backend')
+        .option('--tmux', 'Force the tmux backend')
+        .option('--vscodium', 'Force the VSCodium agent-terminal backend (swarm-ext)')
+        .option('--tabs', 'One tab per session (default: pack two panes per tab)');
+    setHelpSections(cmd, {
+        examples: `
+      # Pick several sessions; they pack two-per-tab in your current terminal
+      agents sessions resume
+
+      # Pre-filter the pool before selecting (space in the filter → use [query])
+      agents sessions resume "auth middleware"
+
+      # Force a backend / one tab each / a remote host
+      agents sessions resume --ghostty
+      agents sessions resume --vscodium
+      agents sessions resume --tabs
+      agents sessions resume --host zion --tmux
+    `,
+        notes: `
+      - space toggles a session, enter confirms; tab toggles the preview pane.
+      - Layout: two-per-tab by default (session 1 → new tab, session 2 → split beside it, …). --tabs disables splitting.
+      - VSCodium defaults to one editor tab per session (matches swarm-ext's native agent-terminal UX); the others default to two-per-tab.
+      - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux/--vscodium.
+      - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --host too).
+      - --host <alias> resumes on a remote machine over the same SSH transport as 'sessions --host' (defaults to tmux).
+      - Each session opens version-pinned, in its own cwd. Non-resumable agents are skipped with a note.
+    `,
+    });
+    cmd.action(async (query, options) => {
+        await sessionsResumeAction(query, options);
+    });
+}
+async function sessionsResumeAction(query, options) {
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('sessions resume needs an interactive terminal.'));
+        process.exitCode = 1;
+        return;
+    }
+    const { agent, version } = parseAgentFilter(options.agent);
+    const limit = parseInt(options.limit || '200', 10);
+    const since = options.since ?? (options.all ? undefined : '30d');
+    let sessions = await discoverSessions({
+        agent,
+        version,
+        all: options.all,
+        cwd: process.cwd(),
+        since,
+        sortBy: 'timestamp',
+        limit,
+        excludeTeamOrigin: !options.teams,
+    });
+    const { visible } = filterTeamSessions(sessions, !!options.teams);
+    sessions = visible;
+    if (sessions.length === 0) {
+        console.log(chalk.gray('No sessions found. Try --all or a different --since window.'));
+        return;
+    }
+    // 1. Multi-select the sessions. gutter: 6 = the multi-select cursor + checkbox
+    // ('> [x] ') that multiItemPicker prepends, so rows size to fit without wrapping.
+    const cols = { ...pickerColumnsFor(sessions), gutter: 6 };
+    let chosen;
+    try {
+        chosen = await multiItemPicker({
+            message: 'Select sessions to resume:',
+            items: sessions,
+            filter: (q) => (q.trim() ? filterSessionsByQuery(sessions, q) : sessions),
+            labelFor: (s, q) => formatPickerLabel(s, q, cols),
+            keyFor: (s) => s.id,
+            buildPreview,
+            pageSize: 15,
+            initialSearch: query,
+            emptyMessage: 'No sessions match.',
+            enterHint: 'resume',
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return;
+        throw err;
+    }
+    if (!chosen || chosen.length === 0)
+        return;
+    // 2. Split the selection into resumable surfaces and skipped agents (no silent drop).
+    const items = [];
+    for (const s of chosen) {
+        const command = buildResumeCommand(s);
+        if (!command) {
+            console.log(chalk.yellow(`  skip ${s.shortId} — resume is not supported for ${s.agent} sessions yet`));
+            continue;
+        }
+        const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
+        items.push({ session: s, cwd, command });
+    }
+    if (items.length === 0) {
+        console.log(chalk.gray('Nothing resumable in the selection.'));
+        return;
+    }
+    // 3. Resolve the backend (and host).
+    const ctx = currentContext();
+    const backend = await resolveBackend(options, ctx, items.length);
+    if (backend === 'cancel')
+        return;
+    // 4. Guard against opening a flood of live agents.
+    if (items.length > CONFIRM_THRESHOLD) {
+        const proceed = await confirm({
+            message: `Open ${items.length} live sessions at once?`,
+            default: false,
+        }).catch(() => false);
+        if (!proceed)
+            return;
+    }
+    // 5a. No tab-capable backend (off-macOS, not in tmux, local) — resume in place, sequentially.
+    if (backend === 'inplace') {
+        if (items.length > 1) {
+            console.log(chalk.gray(`Resuming ${items.length} sessions one at a time (no tab-capable terminal detected).`));
+        }
+        for (const it of items)
+            await resumeSessionInPlace(it.session);
+        return;
+    }
+    // 5b. Fan out through the engine. Split-packing (two-per-tab) suits the
+    // terminal apps; the VSCodium backend defaults to one editor tab per session,
+    // matching swarm-ext's native agent-terminal UX. --tabs forces tabs anywhere.
+    const packing = options.tabs || backend === 'vscodium-agent' ? 'tabs' : 'two-per-tab';
+    const where = options.host ? `${backend} on ${options.host}` : backend;
+    console.log(chalk.gray(`Opening ${items.length} session${items.length === 1 ? '' : 's'} in ${where} (${packing})…`));
+    const results = await openSurfaces(items.map((it) => ({ cwd: it.cwd, command: it.command })), { backend, host: options.host, packing });
+    let opened = 0;
+    results.forEach((r, i) => {
+        const s = items[i].session;
+        if (r.ok) {
+            opened++;
+            const shape = r.request.layout === 'tab' ? 'tab' : 'split';
+            console.log(chalk.green(`  opened ${s.shortId}`) + chalk.gray(` — ${shape} — ${items[i].command.join(' ')}`));
+        }
+        else {
+            console.log(chalk.red(`  failed ${s.shortId} — ${r.error}`));
+        }
+    });
+    console.log(chalk.gray(`\nOpened ${opened}/${items.length} in ${where}.`));
+}
+/**
+ * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
+ * (resume in the current process — no GUI/tmux available), or `'cancel'` (the
+ * user dismissed the chooser).
+ */
+async function resolveBackend(options, ctx, count) {
+    const forced = options.iterm ? 'iterm'
+        : options.ghostty ? 'ghostty'
+            : options.tmux ? 'tmux'
+                : options.vscodium ? 'vscodium-agent'
+                    : undefined;
+    if (forced)
+        return forced;
+    // Remote defaults to tmux (headless, no GUI session assumptions); override with a backend flag.
+    if (options.host)
+        return 'tmux';
+    const available = availableBackends(ctx);
+    if (available.length === 0)
+        return 'inplace';
+    const detected = detectCurrentBackend(ctx);
+    // Only one option and it's where we already are → no need to ask.
+    if (available.length === 1 && (!detected || detected === available[0].id))
+        return available[0].id;
+    const choices = available.map((b) => ({
+        id: b.id,
+        label: b.label,
+        detail: b.id === detected ? "the terminal you're in now" : `open in ${b.label}`,
+    }));
+    try {
+        const picked = await itemPicker({
+            message: `Resume ${count} session${count === 1 ? '' : 's'} where?`,
+            items: choices,
+            filter: () => choices,
+            labelFor: (c) => `${chalk.bold(c.label.padEnd(10))}${chalk.gray(c.detail)}`,
+            shortIdFor: (c) => c.label,
+            enterHint: 'open',
+        });
+        return picked ? picked.item.id : 'cancel';
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return 'cancel';
+        throw err;
+    }
+}

package/dist/commands/sessions-tail.d.ts

@@ -1,4 +1,7 @@
 import type { Command } from 'commander';
+import type { SessionMeta, SessionAgentId } from '../lib/session/types.js';
+/** Whether a session's transcript can be live-tailed (append-only JSONL agents). */
+export declare function isTailable(agent: SessionAgentId): boolean;
 export interface TailFileOptions {
     /** If true, emit every line from byte 0 first, then follow. Default false (EOF). */
     fromStart?: boolean;
@@ -15,5 +18,12 @@ export interface TailFileOptions {
  * parent dir until the file appears).
  */
 export declare function tailFile(filePath: string, onLine: (line: string) => void, ac: AbortController, opts?: TailFileOptions): Promise<void>;
+/**
+ * Live-tail one already-resolved session's transcript to stdout until Ctrl+C.
+ * Shared by `agents sessions tail` and `agents logs -f`.
+ */
+export declare function streamSessionTail(session: SessionMeta, options?: {
+    fromStart?: boolean;
+}): Promise<void>;
 /** Attach the `tail` subcommand to an existing `sessions` command. */
 export declare function registerSessionsTailCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-tail.js

@@ -12,6 +12,10 @@ import chalk from 'chalk';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
 import { setHelpSections } from '../lib/help.js';
 const TAIL_SUPPORTED = ['claude', 'codex'];
+/** Whether a session's transcript can be live-tailed (append-only JSONL agents). */
+export function isTailable(agent) {
+    return TAIL_SUPPORTED.includes(agent);
+}
 /**
  * Tail a file: emit each newline-terminated line via onLine as it's written.
  *
@@ -182,6 +186,13 @@ async function runTail(sessionId, options) {
         }
         session = resolved;
     }
+    await streamSessionTail(session, { fromStart: options.fromStart });
+}
+/**
+ * Live-tail one already-resolved session's transcript to stdout until Ctrl+C.
+ * Shared by `agents sessions tail` and `agents logs -f`.
+ */
+export async function streamSessionTail(session, options = {}) {
     const filePath = session.filePath.split('#')[0];
     if (process.stderr.isTTY) {
         process.stderr.write(chalk.gray(`Tailing ${session.agent} ${session.shortId} — ${filePath}\n`) +

package/dist/commands/sessions.d.ts

@@ -1,7 +1,31 @@
 import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
+import type { SessionAgentId, SessionMeta } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { type PickedSession } from './sessions-picker.js';
+/**
+ * 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 declare function indexActiveBySessionId(active: ActiveSession[]): Map<string, ActiveSession>;
+/**
+ * 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 declare function liveGlyphAndPreview(a: ActiveSession | undefined): {
+    glyph: string;
+    preview: string;
+};
+/**
+ * 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 declare function ticketLabel(s: Pick<SessionMeta, 'ticketId' | 'prNumber'>): string;
 /** Grouped + sorted view of active sessions for the --active renderer. */
 export interface ActiveSessionsLayout {
     workspaces: Array<{
@@ -29,7 +53,119 @@ export interface ActiveSessionsLayout {
  *   - sessions within a window/flat bucket: input order preserved
  */
 export declare function groupActiveSessions(sessions: ActiveSession[]): ActiveSessionsLayout;
+/** One machine's active sessions, keeping the within-machine workspace layout. */
+export interface MachineGroup {
+    /** Normalized device id (machineId() form). */
+    machine: string;
+    /** The machine this command is running on — pinned first and marked. */
+    isLocal: boolean;
+    total: number;
+    layout: ActiveSessionsLayout;
+}
+/** Active sessions grouped by the machine they run on. */
+export interface MachineGroupedLayout {
+    machines: MachineGroup[];
+}
+/**
+ * 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 declare function groupSessionsByMachine(sessions: ActiveSession[], localMachine: string): MachineGroupedLayout;
+/**
+ * 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 declare function dedupeByMachineSession(sessions: ActiveSession[]): ActiveSession[];
+/**
+ * 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 declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: string): SessionMeta[];
+/**
+ * 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 declare function overviewProjectKey(s: Pick<SessionMeta, 'project' | 'cwd'>): string;
+export interface OverviewGroup {
+    key: string;
+    total: number;
+    shown: SessionMeta[];
+    more: number;
+    maxTs: string;
+}
+/**
+ * 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 declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap: number): {
+    groups: OverviewGroup[];
+    projectCount: number;
+};
+/**
+ * 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 declare function renderSessionLog(session: SessionMeta): Promise<void>;
+/** Column-visibility flags for the picker row, computed once over the whole pool. */
+export interface PickerColumns {
+    /** Render the machine column (only when the pool spans more than one machine). */
+    showMachine?: boolean;
+    /** Map a full machine id to its compact display form (shared prefix stripped). */
+    machineLabel?: (m: string) => string;
+    /** Total width of the machine column, sized to the widest compacted hostname
+     * in the pool (capped). Falls back to PICKER_MACHINE_W when absent. */
+    machineWidth?: number;
+    /** Render the ticket/PR column (only when at least one row carries a ref). */
+    showTicket?: boolean;
+    /**
+     * Cells the picker prepends before each row: 2 for the single-select cursor
+     * ('> '), 6 for the multi-select cursor + checkbox ('> [x] '). Reserved from
+     * the topic width so rows never wrap. Defaults to 2.
+     */
+    gutter?: number;
+}
+/**
+ * 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 declare function machineLabeler(machines: string[]): (m: string) => string;
+/**
+ * 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 declare function pickerColumnsFor(sessions: SessionMeta[]): PickerColumns;
+export declare function formatPickerLabel(s: SessionMeta, query: string, cols?: PickerColumns): string;
+/**
+ * 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 declare function formatPickerTip(sessions: SessionMeta[]): string;
 export declare function pickSessionInteractive(sessions: SessionMeta[], message?: string, initialSearch?: string, hiddenCount?: number): Promise<PickedSession | null>;
+/**
+ * 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 declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
 /**
  * Build the shell command that resumes a picked session.
  *
@@ -42,7 +178,13 @@ export declare function pickSessionInteractive(sessions: SessionMeta[], message?
  * handler in handlePickedSession retries via buildFallbackCommand.
  */
 export declare function buildResumeCommand(session: SessionMeta): string[] | null;
+interface AgentFilter {
+    agent?: SessionAgentId;
+    version?: string;
+}
+export declare function parseAgentFilter(agentName?: string): AgentFilter;
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
 /** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
+export {};