@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/commands/sessions-browser.js

@@ -16,11 +16,13 @@ import { dynamicPicker } from '../lib/picker.js';
 import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { gatherRemoteList } from '../lib/session/remote-list.js';
+import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { AGENTS } from '../lib/agents.js';
 import { enrichTeamOrigins, safeTeamText } from '../lib/session/team-filter.js';
 import { listFavorites, toggleFavorite } from '../lib/session/favorites.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { buildPreview } from './sessions-picker.js';
-import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, ticketLabel, mergeLocalFirst, gatherActiveSessions, liveHostLabel, LIVE_ROW_PREFIX, cleanPreview, handlePickedSession, shouldIncludeLocal, remoteHostsToDial, matchesTeam, formatLiveStatusHeadline, matchesLiveStatus, parseAgentFilter, } from './sessions.js';
 /**
  * Complete a seed into the filter the picker actually runs on.
  *
@@ -44,6 +46,15 @@ export function buildInitialFilter(initial) {
         team: initial.team,
         projectScope: initial.projectScope ?? 'repo',
         window: 'window' in initial ? initial.window : '30d',
+        statuses: initial.statuses ?? [],
+        project: initial.project,
+        until: initial.until,
+        routine: initial.routine ?? false,
+        skill: initial.skill,
+        plugin: initial.plugin,
+        limit: initial.limit ?? 500,
+        unmanaged: initial.unmanaged ?? false,
+        sort: initial.sort ?? 'timestamp',
     };
 }
 /** Cache key for the transcript pool: every filter that changes what is FETCHED
@@ -54,7 +65,11 @@ function poolCacheKey(f) {
     // fetches the same deep pool and is then narrowed in memory. Keying on the name
     // would make `t` the one hotkey that re-fans-out the fleet on every step of the
     // cycle, at up to REMOTE_TIMEOUT_MS per unreachable peer.
-    return `${f.window ?? 'all'}|${f.teams}|${f.team ? 'team' : ''}`;
+    const versionScoped = f.agent?.includes('@') ? f.agent : '';
+    return [
+        f.window ?? 'all', f.until ?? '', f.teams, f.team ? 'team' : '', versionScoped,
+        f.project ?? '', f.routine, f.skill ?? '', f.plugin ?? '', f.limit, f.unmanaged, f.sort,
+    ].join('|');
 }
 /** Pool size when a team filter is active; one team's rows can sit anywhere. */
 const WHOLE_TEAM_POOL_LIMIT = 5000;
@@ -105,8 +120,10 @@ export function sessionMatchesQuery(s, query) {
  */
 export function browserFilterToArgv(f, query = '') {
     const a = ['sessions'];
-    if (f.running)
+    if (f.statuses.length === 0 && f.running)
         a.push('--active');
+    for (const status of f.statuses)
+        a.push(`--${status === 'orphaned' ? 'orphan' : status}`);
     if (f.teams)
         a.push('--teams');
     if (f.favorites)
@@ -121,6 +138,22 @@ export function browserFilterToArgv(f, query = '') {
         a.push('--all');
     if (f.window)
         a.push('--since', f.window);
+    if (f.until)
+        a.push('--until', f.until);
+    if (f.project)
+        a.push('--project', f.project);
+    if (f.routine)
+        a.push('--routine');
+    if (f.skill)
+        a.push('--skill', f.skill);
+    if (f.plugin)
+        a.push('--plugin', f.plugin);
+    if (f.unmanaged)
+        a.push('--unmanaged');
+    if (f.sort !== 'timestamp')
+        a.push('--sort', f.sort === 'cost' ? 'cost' : 'duration');
+    if (f.limit !== 500)
+        a.push('--limit', String(f.limit));
     const q = query.trim();
     if (q)
         a.push(JSON.stringify(q));
@@ -151,6 +184,7 @@ export function activeBrowserSeed(opts) {
         // --all widens the window to all-time (project is already 'all' here);
         // --since still overrides.
         window: opts.since ?? (opts.all ? undefined : '30d'),
+        statuses: [],
     };
 }
 /**
@@ -184,6 +218,7 @@ export function bareBrowserSeed(opts) {
         // --all maxes every non-status filter: all dirs AND all-time. --since wins.
         projectScope: opts.all || scoped || wholeTeam ? 'all' : 'repo',
         window: opts.since ?? (opts.all || wholeTeam ? undefined : '30d'),
+        statuses: [],
     };
 }
 /** Copy text to the OS clipboard (best-effort; silently no-ops if unavailable). */
@@ -214,8 +249,13 @@ function copyToClipboard(text) {
  * `hosts` is the explicit `--host`/`--device` scope (if any): it restricts which
  * peers are dialed and whether local is included, honoring the flag's "scope,
  * not add" contract instead of always sweeping the whole fleet. */
-async function fetchRawPool(f, self, local, hosts) {
+async function fetchRawPool(f, self, local, hosts, fixedFilters = false) {
     const since = f.window;
+    const selectedAgent = f.agent ? parseAgentFilter(f.agent) : {};
+    const parsedAgent = fixedFilters ? selectedAgent : {};
+    const localAgentVersion = parsedAgent.agent && parsedAgent.agent in AGENTS
+        ? resolveVersionAliasLoose(parsedAgent.agent, parsedAgent.version)
+        : parsedAgent.version;
     let unreachable = [];
     // Local pool: wide (every directory) — device/agent/project are applied in
     // memory so a hotkey toggle is instant and doesn't re-hit the disk. Skipped
@@ -223,16 +263,33 @@ async function fetchRawPool(f, self, local, hosts) {
     let rows = shouldIncludeLocal(hosts, self)
         ? await discoverSessions({
             all: true,
+            agent: parsedAgent.agent,
+            version: localAgentVersion,
+            includeUnmanaged: f.unmanaged,
             cwd: process.cwd(),
             since,
+            until: f.until,
+            project: f.project,
+            origin: f.routine ? 'routine' : undefined,
+            skill: f.skill,
+            plugin: f.plugin,
             excludeTeamOrigin: !f.teams,
             // A team filter reaches back past the usual browse window, so the pool it
             // draws from has to as well — otherwise the newest 500 rows decide which
             // teams exist.
-            limit: f.team ? WHOLE_TEAM_POOL_LIMIT : 500,
-            sortBy: 'timestamp',
+            limit: f.team ? WHOLE_TEAM_POOL_LIMIT : f.limit,
+            sortBy: f.sort,
         })
         : [];
+    // A synced mirror knows which VERSION produced a session, but it cannot know
+    // which version is currently installed as latest/oldest on the origin device.
+    // For an alias selector, keep only this device's rows here and accept peer
+    // rows only from the live query below, where that peer resolves its own
+    // inventory. If the peer is unavailable, an empty/partial result is honest;
+    // widening to cached sessions from every version is not.
+    if (selectedAgent.version === 'latest' || selectedAgent.version === 'oldest') {
+        rows = rows.filter((row) => (row.machine ?? self) === self);
+    }
     // Fleet: fold in peers' own indexes over SSH (no sync), same as the flag path.
     // Skipped under --local. An explicit --host/--device scopes exactly which peers
     // are dialed (undefined = sweep every online device). Best-effort — a fan-out
@@ -251,11 +308,7 @@ async function fetchRawPool(f, self, local, hosts) {
             // the same bug one hop out. A numeric --limit is forwarded rather than
             // --in-team itself, which a peer on an older build would reject as an
             // unknown option and fail the whole fan-out.
-            const forwarded = ['sessions', '--all', '--json', '--limit', String(f.team ? WHOLE_TEAM_POOL_LIMIT : 500)];
-            if (since)
-                forwarded.push('--since', since);
-            if (f.teams)
-                forwarded.push('--teams');
+            const forwarded = remotePoolArgs(f, fixedFilters);
             const remoteResult = await gatherRemoteList(forwarded, remoteHosts);
             unreachable = remoteResult.unreachable;
             if (remoteResult.sessions.length > 0)
@@ -272,6 +325,32 @@ async function fetchRawPool(f, self, local, hosts) {
         rows = enrichTeamOrigins(rows);
     return { key: poolCacheKey(f), rows, unreachable };
 }
+/** Build the static peer query. Keeping it pure pins the per-device alias
+ * contract: latest/oldest travel unresolved and are resolved by each peer. */
+export function remotePoolArgs(f, fixedFilters) {
+    const forwarded = ['sessions', '--all', '--json', '--limit', String(f.team ? WHOLE_TEAM_POOL_LIMIT : f.limit)];
+    if (f.window)
+        forwarded.push('--since', f.window);
+    if (f.until)
+        forwarded.push('--until', f.until);
+    if (f.project)
+        forwarded.push('--project', f.project);
+    if (f.routine)
+        forwarded.push('--routine');
+    if (f.skill)
+        forwarded.push('--skill', f.skill);
+    if (f.plugin)
+        forwarded.push('--plugin', f.plugin);
+    if (f.unmanaged)
+        forwarded.push('--unmanaged');
+    if (f.sort !== 'timestamp')
+        forwarded.push('--sort', f.sort === 'cost' ? 'cost' : 'duration');
+    if (f.agent && (fixedFilters || f.agent.includes('@')))
+        forwarded.push('--agent', f.agent);
+    if (f.teams)
+        forwarded.push('--teams');
+    return forwarded;
+}
 /**
  * A live session's stable row key: its session id when the agent reported one,
  * else a per-machine handle so an id-less live session (a just-booted harness, a
@@ -366,27 +445,74 @@ export function shouldShowHostColumn(f, live, rows) {
     return rows.some((r) => liveHostLabel(live.get(r.id)) !== '');
 }
 /** Apply the cheap in-memory filters (agent / device / project / running / favorites). */
-function applyFilters(rows, live, f, self, favorites) {
+export function applyFilters(rows, live, f, self, favorites) {
     let out = rows;
     // A projected live row is keyed by pid/task when it has no session id, and a
     // favorite is always keyed by a real session id — so an id-less row can never
     // be favorited and correctly drops out here.
     if (f.favorites)
         out = out.filter((r) => favorites.has(r.id));
-    if (f.agent)
-        out = out.filter((r) => r.agent === f.agent);
+    if (f.agent) {
+        const { agent, version: rawVersion } = parseAgentFilter(f.agent);
+        const localVersion = agent && agent in AGENTS
+            ? resolveVersionAliasLoose(agent, rawVersion)
+            : rawVersion;
+        const peerResolvedAlias = rawVersion === 'latest' || rawVersion === 'oldest';
+        out = out.filter((r) => {
+            if (r.agent !== agent)
+                return false;
+            // Only a LIVE peer result may claim it resolved latest/oldest against that
+            // device's installed inventory. A synced mirror is historical data, not a
+            // version-inventory oracle.
+            if (peerResolvedAlias && (r.machine ?? self) !== self)
+                return r._remote === true;
+            if (!localVersion)
+                return true;
+            return r.version === localVersion;
+        });
+    }
     if (f.device)
         out = out.filter((r) => (r.machine ?? self) === f.device);
     if (f.team)
         out = out.filter((r) => matchesTeam(r, f.team));
+    if (f.project) {
+        const q = f.project.toLowerCase();
+        out = out.filter((r) => (r.project ?? '').toLowerCase().includes(q) || (r.cwd ?? '').toLowerCase().includes(q));
+    }
     if (f.projectScope === 'repo') {
         const cwd = process.cwd();
         out = out.filter((r) => !!r.cwd && (r.cwd === cwd || r.cwd.startsWith(cwd + '/')));
     }
     if (f.running)
         out = out.filter((r) => live.has(r.id));
+    if (f.statuses.length > 0) {
+        out = out.filter((r) => {
+            const active = live.get(r.id);
+            return !!active && f.statuses.some((status) => matchesLiveStatus(active, status));
+        });
+    }
     return out;
 }
+/** One-shot form of the browser's canonical candidate pipeline. Focus uses this
+ * instead of maintaining a second discovery/filter implementation. */
+export async function collectSessionCandidates(initial, opts = {}) {
+    const self = machineId();
+    const filter = buildInitialFilter(initial);
+    if (filter.statuses.length > 0)
+        filter.running = true;
+    const hosts = opts.hosts && opts.hosts.length > 0 ? opts.hosts : undefined;
+    const pool = await fetchRawPool(filter, self, opts.local ?? false, hosts, true);
+    let liveById = new Map();
+    if (filter.running || opts.includeLive) {
+        const { sessions } = await gatherActiveSessions({ local: opts.local ?? false, hosts });
+        liveById = indexLiveRows(sessions, self);
+    }
+    const rows = filter.running || opts.includeLive
+        ? mergeLiveIntoPool(pool.rows, liveById, self)
+        : pool.rows;
+    const sessions = applyFilters(rows, liveById, filter, self, listFavorites());
+    return { sessions, liveById, self, unreachable: pool.unreachable };
+}
 /** Derive the SSH-launch origin tag for a picker row from the live index. Set
  * only when the live session's provenance is ssh transport; `device` is the
  * resolved origin device (absent → the row shows a bare `ssh`). Rows without a

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

@@ -1,6 +1,9 @@
 import type { Command } from 'commander';
-import { type Packing } from '../lib/terminal/index.js';
-interface ResumeOptions {
+import type { SessionMeta } from '../lib/session/types.js';
+import { type Backend, type EngineContext, type Packing } from '../lib/terminal/index.js';
+/** Opening more than this many live sessions at once asks for confirmation first. */
+export declare const CONFIRM_THRESHOLD = 5;
+export interface ResumeOptions {
     agent?: string;
     all?: boolean;
     teams?: boolean;
@@ -16,5 +19,22 @@ interface ResumeOptions {
     splits?: boolean;
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
+/** IDs and tmux aliases are actions, not picker search text. Human phrases keep
+ * the existing pre-filtered picker, while an explicit identity resumes directly. */
+export declare function isDirectResumeSelector(query: string): boolean;
+/** Re-enter through the top-level command so fleet routing and harness policy
+ * stay centralized. The child inherits this terminal for a real interactive resume. */
+export declare function resumeSelectorInPlace(selector: string): Promise<void>;
+/** Direct identities use focus as the lifecycle dispatcher: it rechecks the
+ * live fleet, attaches a healthy pane, and falls through to `agents resume`
+ * only when the process is no longer attachable. */
+export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[]): Promise<void>;
+export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[]): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
-export {};
+export declare function resumeHostMismatch(session: Pick<SessionMeta, 'shortId' | 'machine'>, requestedHost: string, self?: string): string | null;
+/**
+ * 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).
+ */
+export declare function resolveBackend(options: ResumeOptions, ctx: EngineContext, count: number): Promise<Backend | 'inplace' | 'cancel'>;

package/dist/commands/sessions-resume.js

@@ -14,24 +14,28 @@ 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 { filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, buildSessionRecoveryCommand, 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';
+import { spawn } from 'node:child_process';
+import { looksLikeSessionId } from '../lib/session/discover.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
-const CONFIRM_THRESHOLD = 5;
+export 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).')
+        .argument('[query]', 'Session id/tmux alias to reopen directly, or text that filters the picker')
+        .description('Reopen one session by canonical identity, or multi-select history into terminal tabs/splits.')
         .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('--host <alias>', 'Open on the session origin host over SSH; the host must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
         .option('--tmux', 'Force the tmux backend')
@@ -46,6 +50,10 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       # Pre-filter the pool before selecting (space in the filter → use [query])
       agents sessions resume "auth middleware"
 
+      # Reopen one session from any device by UUID prefix or tmux alias
+      agents sessions resume 019fd114
+      agents sessions resume ag-codex-c1f3d813
+
       # Force a backend / side-by-side splits / a remote host
       agents sessions resume --ghostty
       agents sessions resume --vscodium
@@ -53,12 +61,13 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       agents sessions resume --host zion --tmux
     `,
         notes: `
-      - space toggles a session, enter confirms; tab toggles the preview pane.
+      - A UUID/prefix or ag-<agent>-<suffix> alias bypasses the picker: a live pane is attached; an inactive session resumes on its owning device.
+      - With no identity selector, space toggles a session, enter confirms, and tab toggles the preview pane.
       - Layout: one tab per session by default. --splits packs session pairs side by side in each 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.
+      - --host <alias> opens the terminal surface on that host only when it is the selected sessions' origin; recovery never migrates a session to another device.
+      - Recovery runs on the session's origin device: exact healthy origin uses native resume; otherwise a healthy version of the same harness receives /continue <id>.
     `,
     });
     cmd.action(async (query, options) => {
@@ -71,6 +80,10 @@ async function sessionsResumeAction(query, options) {
         process.exitCode = 1;
         return;
     }
+    if (query && isDirectResumeSelector(query)) {
+        await dispatchSessionLifecycleInPlace(query.trim(), options.host ? [options.host] : []);
+        return;
+    }
     const { agent, version } = parseAgentFilter(options.agent);
     const limit = parseInt(options.limit || '200', 10);
     const since = options.since ?? (options.all ? undefined : '30d');
@@ -115,21 +128,25 @@ async function sessionsResumeAction(query, options) {
     }
     if (!chosen || chosen.length === 0)
         return;
-    // 2. Split the selection into resumable surfaces and skipped agents (no silent drop).
+    if (options.host) {
+        const requestedHost = options.host;
+        const mismatches = chosen
+            .map((session) => resumeHostMismatch(session, requestedHost))
+            .filter((message) => message !== null);
+        if (mismatches.length > 0) {
+            for (const message of mismatches)
+                console.error(chalk.red(message));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 2. Route every selection through the owning device's recovery resolver.
     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 command = buildSessionRecoveryCommand(s, !!options.host);
         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);
@@ -179,15 +196,52 @@ async function sessionsResumeAction(query, options) {
     });
     console.log(chalk.gray(`\nOpened ${opened}/${items.length} in ${where}.`));
 }
+/** IDs and tmux aliases are actions, not picker search text. Human phrases keep
+ * the existing pre-filtered picker, while an explicit identity resumes directly. */
+export function isDirectResumeSelector(query) {
+    const selector = query.trim();
+    return looksLikeSessionId(selector) || /^ag-[a-z][a-z0-9-]*-[0-9a-f]{8}$/i.test(selector);
+}
+/** Re-enter through the top-level command so fleet routing and harness policy
+ * stay centralized. The child inherits this terminal for a real interactive resume. */
+export async function resumeSelectorInPlace(selector) {
+    await spawnCliInPlace(['resume', selector]);
+}
+/** Direct identities use focus as the lifecycle dispatcher: it rechecks the
+ * live fleet, attaches a healthy pane, and falls through to `agents resume`
+ * only when the process is no longer attachable. */
+export async function dispatchSessionLifecycleInPlace(selector, hosts = []) {
+    await spawnCliInPlace(buildSessionLifecycleArgs(selector, hosts));
+}
+export function buildSessionLifecycleArgs(selector, hosts = []) {
+    return ['sessions', 'focus', selector, ...hosts.flatMap(host => ['--host', host])];
+}
+function asyncExitCode(child) {
+    return new Promise((resolve) => {
+        child.once('error', () => resolve(127));
+        child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+}
+async function spawnCliInPlace(args) {
+    const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: 'inherit' });
+    const exitCode = await asyncExitCode(child);
+    process.exitCode = exitCode;
+}
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
+export function resumeHostMismatch(session, requestedHost, self = machineId()) {
+    const origin = sessionOriginDevice(session, self);
+    return sessionRecoveryDestinationMatches(session, requestedHost, self)
+        ? null
+        : `Session ${session.shortId} originated on ${origin}; --host ${requestedHost} cannot move recovery to another device.`;
+}
 /**
  * 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) {
+export async function resolveBackend(options, ctx, count) {
     const forced = options.iterm ? 'iterm'
         : options.ghostty ? 'ghostty'
             : options.tmux ? 'tmux'

package/dist/commands/sessions.d.ts

@@ -66,6 +66,9 @@ interface SessionsOptions extends SessionFilterOptions {
     local?: boolean;
     /** --device <target...> — alias for --host; resolves against the device registry. */
     device?: string[];
+    /** --devices <target...> — plural alias for --device; a bare `all`/`fleet` value
+     * means "search the whole fleet" (already the default), so it never errors. */
+    devices?: string[];
     /** Query every registered online compute device and merge tool evidence. */
     fleet?: boolean;
     /** Aggregate static program sites instead of returning matching call evidence. */
@@ -127,6 +130,17 @@ export declare function formatActiveRowDescription(s: ActiveSession): string;
  * can't be correlated back to a transcript on disk.
  */
 export declare function indexActiveBySessionId(active: ActiveSession[]): Map<string, ActiveSession>;
+/** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
+type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber'>;
+/**
+ * Backfill display-only fields onto live rows from the indexed SessionMeta, by
+ * full session id (RUSH-2205). A running process reports no agent version, and a
+ * live orphan row usually carries no ticket/PR/label/start-time; the historical
+ * index does. Only a field the live row LACKS is filled — the live signal always
+ * wins when present. Pure (no I/O) so the join is unit-tested against fixtures;
+ * the DB read that builds `metaById` is the caller's concern.
+ */
+export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
 /**
  * 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
@@ -198,6 +212,22 @@ export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]
     prLink: string | null;
     viewingIn: string | null;
 }>;
+/**
+ * Build the (one or two) rendered lines for a single active-session row.
+ * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a window
+ * sub-group). Sized to `termW` so no line ever wraps under tmux/SSH (RUSH-2205):
+ *
+ *   line 1: id · agent version · status · owner · created X · idle Y · ticket/PR
+ *   line 2: └ label/topic (+ checklist) · jump locator (ssh/tmux/detached)
+ *
+ * The label/topic gets its own line so it is no longer buried in a truncated grey
+ * snippet, and the actionable ticket/PR badges ride line 1. Version and the
+ * ticket/PR/label are backfilled onto the {@link ActiveSession} from the indexed
+ * SessionMeta before this renders (a live process reports none of them). Pure +
+ * exported so the row layout is unit-tested for content and width without a
+ * captured stdout.
+ */
+export declare function renderActiveRowLines(s: ActiveSession, indent: string, termW: number): string[];
 /**
  * Compact owner display for the `--active` owner column: the local-part of a
  * resolved actor email/login (`muqsit@getrush.ai` -> `muqsit`), the id as-is
@@ -313,10 +343,17 @@ export declare function remoteHostsToDial(hosts: string[] | undefined, self: str
  * call it, so the browser can never disagree with `--active --json` about which
  * sessions are live (it used to call the local-only `getActiveSessions()` directly
  * and silently hid every remote session).
+ *
+ * RUSH-2062: default path is cache-first against the daemon-warmed shared
+ * snapshot (`session-cache.ts`). Menubar / Factory / watchdog / CLI share one
+ * warm result instead of each re-running the full SSH fan-out. `forceRefresh`
+ * (or `AGENTS_SESSIONS_FORCE_REFRESH=1`) re-gathers live; scoped `--host` lists
+ * always gather live so a filter never returns a wrong unscoped snapshot.
  */
 export declare function gatherActiveSessions(opts?: {
     local?: boolean;
     hosts?: string[];
+    forceRefresh?: boolean;
 }): Promise<{
     sessions: ActiveSession[];
     remoteDeviceCount: number;
@@ -536,6 +573,13 @@ export declare function handlePickedSession(picked: PickedSession): Promise<void
  * version-pinned launcher is genuinely missing.
  */
 export declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
+/**
+ * Relaunch this CLI's one recovery path. The owning device resolves account
+ * health and either performs exact-home native resume or same-harness
+ * `/continue`; callers never guess which version home can see the transcript.
+ * `portable` is for an SSH/terminal-engine command that executes on a peer.
+ */
+export declare function buildSessionRecoveryCommand(session: Pick<SessionMeta, 'id'>, portable?: boolean): string[];
 /**
  * Map a resume argv to the spawn(command, args, {shell}) triple.
  *
@@ -557,6 +601,9 @@ interface AgentFilter {
     agent?: SessionAgentId;
     version?: string;
 }
+/** Resolve the harness portion of a sessions selector with the CLI's canonical
+ * alias and single-typo rules. Kept pure so focus and the browser cannot drift. */
+export declare function resolveSessionAgentName(name: string): SessionAgentId | null;
 export declare function parseAgentFilter(agentName?: string): AgentFilter;
 /**
  * How a `sessions <query>` argument was resolved against the pool.
@@ -582,6 +629,10 @@ export interface SessionQueryResolution {
 export declare function resolveSessionQuery(pool: SessionMeta[], query: string, options?: {
     indexFallback?: boolean;
 }): SessionQueryResolution;
+/** Honest result of a fleet sweep that found nothing: it says what the sweep
+ * actually did — how many peers answered, which were unreachable — instead of
+ * dead-ending on "search with --device <host>" after the search already ran. */
+export declare function fleetNotFoundMessage(query: string, deviceCount: number, unreachable: string[]): string[];
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
 /**
@@ -626,11 +677,32 @@ export type MetadataResolveOutcome = {
     kind: 'partial';
     failedPeers: string[];
 };
+/**
+ * A match unique enough to resolve on the FIRST peer that returns it and cancel
+ * the rest of the fleet sweep: a full session UUID, which is globally unique.
+ *
+ * Only a full UUID qualifies. A session **label** is deliberately NOT definitive
+ * here even on an exact match: labels are free-form and can collide, so a
+ * distinct session may carry the same label on a peer that has not answered yet
+ * — early-exiting on the first would silently, and nondeterministically, resume
+ * the wrong session (whichever peer replied first). Labels therefore stay
+ * all-settle so a cross-machine label conflict surfaces as an ambiguity, and a
+ * short-id PREFIX stays all-settle for the same reason (RUSH-2203).
+ */
+export declare function isDefinitiveMatch(session: SessionMeta, selector: string): boolean;
+/**
+ * Whether a selector may enable early-exit on the cancellable fan-out — only a
+ * full UUID, which is globally unique so the first hit is the only hit. Labels,
+ * keywords, and short-id prefixes stay all-settle: their uniqueness (or
+ * conflict) is only knowable once every peer has answered. See
+ * {@link isDefinitiveMatch}.
+ */
+export declare function selectorAllowsEarlyExit(selector: string): boolean;
 /** Resolve a fleet sweep through the same canonical full-id / prefix resolver as
  * local lookups, then group copies by logical session id. Synced mirrors of one
  * session therefore stay one candidate even when several machines report them;
  * distinct ids sharing a prefix remain distinct ambiguity candidates. */
-export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: string): FleetSessionCandidate[];
+export declare function fleetCandidatesByQuery(rows: SessionMeta[], query: string, trustResolvedRows?: boolean): FleetSessionCandidate[];
 /** Fixed peer argv for the metadata resolver. Scope flags compose identically on
  * every host; `--all` removes the SSH login cwd/time window, not agent/project filters. */
 export declare function metadataResolveForwardedArgs(selector: string, scope: Pick<SessionFilterOptions, 'agent' | 'project'>): string[];
@@ -661,14 +733,28 @@ export declare function resolveSessionMetadataValue(selector: string, scope?: {
  *     (its transcript and agent binary live there — a local `--host` hop would
  *     re-discover locally and dead-end), returning `'rendered'`.
  *   - more than one logical session → print every full-id candidate with its
- *     machine labels, returning `'conflict'`.
- *   - none                 → `'not-found'`, letting the caller print the local
- *     "no session on this machine" message.
+ *     machine labels, returning `{ kind: 'conflict' }`.
+ *   - none                 → `{ kind: 'not-found', deviceCount, unreachable }`,
+ *     letting the caller print an honest sweep-aware message.
+ *
+ * A full-UUID query opts into early-exit: the first peer holding it resolves the
+ * sweep and cancels the rest, so a fast peer is not bounded by the slowest one.
+ * A short-id prefix stays all-settle — its ambiguity is only known once every
+ * peer has answered, so it must wait to surface a conflict.
  *
  * No fuzzy/content fallback: the sweep forwards the id selector and every result
  * is resolved through `resolveSessionQuery`, the same id-only resolver used locally.
  */
-export declare function resolveSessionAcrossFleet(query: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<'rendered' | 'conflict' | 'not-found'>;
+export type FleetResolveResult = {
+    kind: 'rendered';
+} | {
+    kind: 'conflict';
+} | {
+    kind: 'not-found';
+    deviceCount: number;
+    unreachable: string[];
+};
+export declare function resolveSessionAcrossFleet(query: string, mode: ViewMode, hosts?: string[], deps?: FleetResolveDeps): Promise<FleetResolveResult>;
 /** Register the `agents sessions` command with all its options and help text. */
 export declare function registerSessionsCommands(program: Command): void;
 export {};