@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/dist/commands/secrets.d.ts

@@ -18,3 +18,23 @@ export { SSH_TARGET_RE, assertValidSshTarget };
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
+ * NO quoting of its own, so an unquoted arg with a space is split into several
+ * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
+ * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
+ * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
+ * rules, so the *child's* argv parse reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * `agents secrets exec` runs a caller-supplied command against a bundle the
+ * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
+ * ever changes (exec'ing an untrusted command line), route through a shell that
+ * disables expansion rather than relying on this quoter. An empty arg becomes
+ * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
+ * under `process.platform === 'win32'`).
+ */
+export declare function quoteWin32ExecArg(arg: string): string;

package/dist/commands/secrets.js

@@ -7,9 +7,9 @@
  */
 import { Option } from 'commander';
 import chalk from 'chalk';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
-import { spawnSync } from 'child_process';
-import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
+import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, resolveSshTarget, } from '../lib/secrets/remote.js';
 import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
@@ -270,8 +270,10 @@ function renderPolicyCol(b, held) {
     const exp = held?.get(b.name);
     return exp ? chalk.green(`daily · ${compactRemaining(exp)} left`) : chalk.gray('daily');
 }
+/** Below this width the fixed date columns no longer fit; `list` uses cards. */
+const SECRETS_WIDE = 96;
 /** Format a single bundle as a table row for the `secrets list` output. */
-function renderBundleRow(b, held) {
+function renderBundleRow(b, held, cols = terminalWidth()) {
     const entries = describeBundle(b);
     const keys = entries.length;
     const expiringCount = countExpiringSoon(b.meta);
@@ -296,10 +298,26 @@ function renderBundleRow(b, held) {
         `${padVisible(used, 7)}`;
     // Mark file-backed bundles so `list` distinguishes them from keychain ones.
     const tag = b.backend === 'file' ? chalk.magenta('[file] ') : '';
-    const desc = b.description ? chalk.gray(safePrint(b.description)) : '';
+    // Cap the free-form description to whatever space is left on the line so a long
+    // description can't push the row to 200+ chars and wrap into a smear.
+    const budget = cols - stringWidth(head) - 1 - stringWidth(tag);
+    const desc = b.description && budget > 3
+        ? chalk.gray(truncateToWidth(safePrint(b.description), budget))
+        : '';
     const trailer = `${tag}${desc}`.trimEnd();
     return trailer ? `${head} ${trailer}` : head.trimEnd();
 }
+/** Narrow-terminal card: name + compact meta on one line, description below. */
+function renderBundleCard(b, held, cols) {
+    const keys = describeBundle(b).length;
+    const used = b.last_used ? relativeAge(b.last_used) : (b.created_at ? 'never' : '?');
+    const tag = b.backend === 'file' ? chalk.magenta(' [file]') : '';
+    const meta = chalk.gray(`${keys} key${keys === 1 ? '' : 's'} · `) + renderPolicyCol(b, held) + chalk.gray(` · used ${used}`);
+    const line1 = `${chalk.cyan(b.name)}  ${meta}${tag}`;
+    if (!b.description)
+        return line1;
+    return `${line1}\n    ${chalk.gray(truncateToWidth(safePrint(b.description), cols - 4))}`;
+}
 /** Colorize a variable source kind (literal, keychain, env, file, exec). */
 function kindLabel(kind) {
     switch (kind) {
@@ -519,9 +537,17 @@ export function registerSecretsCommands(program) {
                 /* broker not running — render policy without the countdown */
             }
         }
-        console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(18)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
-        for (const b of bundles) {
-            console.log(renderBundleRow(b, held));
+        const cols = terminalWidth();
+        if (cols >= SECRETS_WIDE) {
+            console.log(chalk.bold(`${'NAME'.padEnd(20)} ${'KEYS'.padEnd(5)} ${'POLICY'.padEnd(18)} ${'EXPIRING'.padEnd(9)} ${'CREATED'.padEnd(9)} ${'UPDATED'.padEnd(9)} ${'USED'.padEnd(7)} DESCRIPTION`));
+            for (const b of bundles) {
+                console.log(renderBundleRow(b, held, cols));
+            }
+        }
+        else {
+            for (const b of bundles) {
+                console.log(renderBundleCard(b, held, cols));
+            }
         }
     });
     cmd
@@ -1218,20 +1244,18 @@ Examples:
                 const remoteCmd = `bash -lc ${shellQuote(remoteAgents)}`;
                 let failures = 0;
                 for (const host of hosts) {
-                    const res = spawnSync('ssh', ['-o', 'BatchMode=yes', host, remoteCmd], {
-                        input,
-                        stdio: ['pipe', 'pipe', 'pipe'],
-                        encoding: 'utf-8',
-                    });
-                    if (res.error) {
+                    // Routed through the shared ssh engine: full hardened options
+                    // (BatchMode, ConnectTimeout, keepalive) + control-socket reuse.
+                    const res = sshExec(host, remoteCmd, { input });
+                    if (res.code === null) {
                         failures++;
-                        console.error(chalk.red(`${host}: ${res.error.message}`));
+                        console.error(chalk.red(`${host}: ${res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed')}`));
                         continue;
                     }
-                    if (res.status !== 0) {
+                    if (res.code !== 0) {
                         failures++;
                         const msg = (res.stderr || res.stdout || '').trim();
-                        console.error(chalk.red(`${host}: remote import failed (exit ${res.status ?? 'signal'})${msg ? `: ${msg}` : ''}`));
+                        console.error(chalk.red(`${host}: remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`));
                         continue;
                     }
                     const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
@@ -1325,8 +1349,18 @@ Examples:
                 secretEnv = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` }).env;
             }
             const { spawn } = await import('child_process');
-            const proc = spawn(cmd, args, {
+            // On Windows, spawn without a shell ENOENTs for `.cmd`/`.bat` launchers
+            // (npm, yarn, most JS CLIs) and shell built-ins, so we set shell:true.
+            // With shell:true Node hands cmd.exe a single command line with NO quoting
+            // of its own, so args containing spaces or cmd metacharacters must be
+            // quoted here (quoteWin32ExecArg) or they'd be split. See that helper for
+            // the cmd.exe %VAR%/!VAR! expansion caveat.
+            const useShell = process.platform === 'win32';
+            const spawnCmd = useShell ? quoteWin32ExecArg(cmd) : cmd;
+            const spawnArgs = useShell ? args.map(quoteWin32ExecArg) : args;
+            const proc = spawn(spawnCmd, spawnArgs, {
                 stdio: 'inherit',
+                shell: useShell,
                 env: { ...process.env, ...secretEnv },
             });
             proc.on('close', (code) => process.exit(code ?? 0));
@@ -1619,6 +1653,48 @@ function humanRemaining(expiresAt) {
     const days = Math.round(hours / 24);
     return `locks in ${days} day${days === 1 ? '' : 's'}`;
 }
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
+ * NO quoting of its own, so an unquoted arg with a space is split into several
+ * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
+ * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
+ * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
+ * rules, so the *child's* argv parse reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * `agents secrets exec` runs a caller-supplied command against a bundle the
+ * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
+ * ever changes (exec'ing an untrusted command line), route through a shell that
+ * disables expansion rather than relying on this quoter. An empty arg becomes
+ * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
+ * under `process.platform === 'win32'`).
+ */
+export function quoteWin32ExecArg(arg) {
+    if (arg.length > 0 && !/[\s"&|<>()^]/.test(arg))
+        return arg;
+    let result = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            backslashes += 1;
+            continue;
+        }
+        if (ch === '"') {
+            // Double the run of backslashes, then escape this quote.
+            result += '\\'.repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        result += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // Trailing backslashes precede the closing quote → must be doubled.
+    result += '\\'.repeat(backslashes * 2) + '"';
+    return result;
+}
 /**
  * Copy text to the system clipboard, cross-platform.
  * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then

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,209 @@
+/**
+ * `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, 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; 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('--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 --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.
+      - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux.
+      - --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.
+    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),
+            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 (two-per-tab by default).
+    const packing = options.tabs ? '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' : 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,49 @@ 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[];
+/**
+ * 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>;
+export declare function formatPickerLabel(s: SessionMeta, query: string): 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 +108,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 {};