@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/commands/sessions.js

@@ -20,34 +20,39 @@ import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
-import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecutable, composeWin32CommandLine } from '../lib/platform/index.js';
+import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, composeWin32CommandLine } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
 import { resolveViewingIn, viewingInLabel } from '../lib/session/viewing-in.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
+import { loadFleetActiveSessions, loadLocalActiveSessions, } from '../lib/session/session-cache.js';
 import { gatherRemoteList, gatherRemoteToolProgramCounts, gatherRemoteToolSearch, runOnPeer } from '../lib/session/remote-list.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
 import { discoverSessions, queryIndexedSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, looksLikeSessionId, searchContentIndex, getSessionRoots, scopeToManaged } from '../lib/session/discover.js';
-import { findSessionsById, querySessions } from '../lib/session/db.js';
+import { findSessionsById, querySessions, getSessionById } from '../lib/session/db.js';
 import { filterTeamSessions, safeTeamText } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
-import { formatRelativeTime, sessionAgeParts } from '../lib/session/relative-time.js';
+import { formatRelativeTime, formatCompactAge, sessionAgeParts } from '../lib/session/relative-time.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList, linkPath, linkUrl, shortenModel } from '../lib/session/render.js';
 import { linearIssueUrl } from '../lib/session/linear.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
 import { getShimsDir } from '../lib/state.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
+import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { getAgentsInvocation } from '../lib/daemon.js';
+import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker, buildPreview, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
+import { registerSessionsForkCommand } from './fork.js';
 import { registerSessionsFavoriteCommand } from './sessions-favorite.js';
 import { isFavorite, listFavorites } from '../lib/session/favorites.js';
 import { registerGoCommand } from './go.js';
@@ -378,6 +383,58 @@ export function indexActiveBySessionId(active) {
     }
     return byId;
 }
+/**
+ * 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 function backfillActiveRowsFromMeta(sessions, metaById) {
+    for (const s of sessions) {
+        if (!s.sessionId)
+            continue;
+        const m = metaById.get(s.sessionId);
+        if (!m)
+            continue;
+        if (!s.version && m.version)
+            s.version = m.version;
+        if (!s.label && m.label)
+            s.label = m.label;
+        if (!s.ticket && m.ticketId)
+            s.ticket = { id: m.ticketId, url: linearIssueUrl(m.ticketId) };
+        if (!s.pr && m.prUrl)
+            s.pr = { url: m.prUrl, number: m.prNumber };
+        if (!s.startedAtMs && m.timestamp) {
+            const ts = new Date(m.timestamp).getTime();
+            if (!Number.isNaN(ts))
+                s.startedAtMs = ts;
+        }
+    }
+}
+/**
+ * Build the id→meta index the live-row backfill needs, reading the historical
+ * session DB by full id. Best-effort: a missing or locked DB yields an empty map
+ * so the live view still renders (mirrors {@link maybeLiveIndex}). Deduplicates
+ * ids so N rows in one session cost one query.
+ */
+function loadBackfillMetaFor(sessions) {
+    const byId = new Map();
+    try {
+        for (const s of sessions) {
+            if (!s.sessionId || byId.has(s.sessionId))
+                continue;
+            const m = getSessionById(s.sessionId);
+            if (m)
+                byId.set(s.sessionId, m);
+        }
+    }
+    catch {
+        /* enrichment is best-effort — an unavailable DB leaves rows un-backfilled */
+    }
+    return byId;
+}
 /**
  * The live decoration for a listing row: a status glyph and the latest-turn
  * preview, when the session is still running. `●` running / `◐` waiting on the
@@ -582,30 +639,109 @@ function locatorBadge(s) {
     return parts.join(' ');
 }
 /**
- * Render a single agent-session row inside an already-printed group header.
- * Indent is the leading whitespace (2 spaces for flat groups, 4 inside a
- * window sub-group). Leads with the 8-char session id (the address to read or
- * resume it); status, badges, and the live preview fill the rest, sized to the
- * terminal width so the row never wraps.
+ * The `created X · idle Y` time cell for a live row (RUSH-2205). `created` is the
+ * age of the session start ({@link ActiveSession.startedAtMs}); `idle` is the age
+ * of the last transcript write ({@link ActiveSession.lastActivityMs}) — i.e. how
+ * long it has been quiet. Compact ("6d", "3h", "now") so the row stays width-safe;
+ * either half is omitted when its epoch is unknown.
  */
-function printActiveRow(s, indent) {
-    // shortId (8-char) · agent · host · status · owner · badges · identity+todos+snippet
-    const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', 9));
-    const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, 8), 9));
-    const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
-    const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
-    const ownerCol = chalk.cyan(padToWidth(truncateToWidth(ownerLabel(s), 8), 9));
+function activeTimeCell(s) {
+    const parts = [];
+    if (s.startedAtMs)
+        parts.push(`created ${formatCompactAge(new Date(s.startedAtMs).toISOString())}`);
+    if (s.lastActivityMs)
+        parts.push(`idle ${formatCompactAge(new Date(s.lastActivityMs).toISOString())}`);
+    return parts.join(' · ');
+}
+/** Column widths for line 1 of an active row (id · agent · version · status · owner). */
+const ROW_ID_W = 9;
+const ROW_AGENT_W = 8;
+const ROW_VERSION_W = 8;
+const ROW_STATUS_W = 9;
+const ROW_OWNER_W = 9;
+/**
+ * Fit pre-styled content (which may carry SGR colour AND OSC-8 hyperlinks — the
+ * clickable ticket/PR/project badges) into `room` display cells. Returns it raw
+ * when it already fits, preserving colour and clickable links; otherwise falls
+ * back to a width-safe truncation. `truncateToWidth` strips OSC-8 before cutting
+ * (see width.ts), so a too-narrow cell drops the hyperlink cleanly rather than
+ * slicing a hyperlink escape in half and corrupting the terminal (RUSH-2205
+ * review). Never run pre-linked content through `truncateToWidth` directly — that
+ * strips its links even when it fits; go through this helper.
+ */
+function fitCell(content, room) {
+    if (room <= 0)
+        return '';
+    return stringWidth(content) <= room ? content : truncateToWidth(content, room);
+}
+/**
+ * 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 function renderActiveRowLines(s, indent, termW) {
+    const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', ROW_ID_W));
+    const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, ROW_AGENT_W), ROW_AGENT_W + 1));
+    const versionCol = chalk.gray(padToWidth(truncateToWidth(s.version ?? '', ROW_VERSION_W), ROW_VERSION_W + 1));
+    const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), ROW_STATUS_W - 1), ROW_STATUS_W));
+    const ownerCol = chalk.cyan(padToWidth(truncateToWidth(ownerLabel(s), ROW_OWNER_W - 1), ROW_OWNER_W));
+    const fixedCols = idCol + kindCol + versionCol + statusCol + ownerCol;
+    const fixedW = stringWidth(indent) + ROW_ID_W + (ROW_AGENT_W + 1) + (ROW_VERSION_W + 1) + ROW_STATUS_W + ROW_OWNER_W;
+    const remaining = Math.max(0, termW - fixedW - 1);
+    // Line 1 right side: created/idle time + actionable badges (fork count,
+    // plan/ask/perm, ticket, PR, worktree). Badges are the jump-to-work signal, so
+    // they win the width fight — fitCell keeps them raw+clickable when they fit and
+    // drops the link cleanly when narrow; the time cell takes whatever is left.
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
-    const badges = (fork ? fork : '') + [signalBadges(s), locatorBadge(s)].filter(Boolean).join(' ');
-    // Identity (label/project/ticket clickable) + checklist + live snippet.
-    // Cross-machine rows use the same path — remote ActiveSession fields arrive
-    // via the SSH fan-out already populated (including todos when the peer has them).
-    const desc = formatActiveRowDescription(s) || '-';
-    // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
-    const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
-    const room = Math.max(12, terminalWidth() - fixed - 1);
-    const descCol = chalk.white(truncateToWidth(desc, room));
-    console.log(indent + idCol + kindCol + hostCol + statusCol + ownerCol + (badges ? badges + ' ' : '') + descCol);
+    const badgesCell = fitCell(fork + signalBadges(s), remaining);
+    const badgesW = stringWidth(badgesCell);
+    const timeRoom = Math.max(0, remaining - (badgesW ? badgesW + 2 : 0));
+    const timeCell = chalk.gray(truncateToWidth(activeTimeCell(s), timeRoom));
+    let right = timeCell;
+    if (badgesCell)
+        right += (stringWidth(timeCell) ? '  ' : '') + badgesCell;
+    // right's visible width is <= remaining by construction, so the assembled line
+    // is <= termW-1 whenever the fixed columns fit; the clamp only bites a terminal
+    // narrower than the fixed columns (where right is empty — no link to corrupt).
+    let line1 = indent + fixedCols + right;
+    if (stringWidth(line1) > termW)
+        line1 = truncateToWidth(line1, termW);
+    const lines = [line1];
+    // Line 2: label/topic + checklist (the identity, no longer buried) then the
+    // jump locator. Skipped entirely when there is nothing to say. desc may carry a
+    // clickable project link, so it also goes through fitCell.
+    const desc = formatActiveRowDescription(s);
+    const loc = locatorBadge(s);
+    if (!desc && !loc)
+        return lines;
+    const contIndent = indent + ' '.repeat(ROW_ID_W);
+    const room2 = Math.max(0, termW - stringWidth(contIndent) - 2);
+    const locCell = fitCell(loc, room2);
+    const locW = stringWidth(locCell);
+    const descRoom = Math.max(0, room2 - (locW ? locW + 2 : 0));
+    const descCell = chalk.white(fitCell(desc || '-', descRoom));
+    let line2 = contIndent + chalk.dim('└ ') + descCell;
+    if (locCell)
+        line2 += '  ' + locCell;
+    if (stringWidth(line2) > termW)
+        line2 = truncateToWidth(line2, termW);
+    lines.push(line2);
+    return lines;
+}
+/** Render a single agent-session row inside an already-printed group header. */
+function printActiveRow(s, indent) {
+    for (const line of renderActiveRowLines(s, indent, terminalWidth()))
+        console.log(line);
 }
 /**
  * Compact owner display for the `--active` owner column: the local-part of a
@@ -1048,8 +1184,48 @@ export function remoteHostsToDial(hosts, self) {
  * 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 async function gatherActiveSessions(opts = {}) {
+    const forceRefresh = opts.forceRefresh === true
+        || process.env.AGENTS_SESSIONS_FORCE_REFRESH === '1';
+    // Scoped host lists are not represented in the unscoped fleet/local snapshot
+    // — always gather live so a filter cannot return the wrong set.
+    const scoped = (opts.hosts?.length ?? 0) > 0;
+    if (opts.local && !scoped) {
+        const loaded = await loadLocalActiveSessions({
+            forceRefresh,
+            gather: async () => {
+                const rows = await getActiveSessions({ localOnly: true });
+                const self = machineId();
+                for (const s of rows)
+                    if (!s.machine)
+                        s.machine = self;
+                return rows;
+            },
+        });
+        return { sessions: loaded.sessions, remoteDeviceCount: 0 };
+    }
+    if (!opts.local && !scoped) {
+        const loaded = await loadFleetActiveSessions({
+            forceRefresh,
+            gather: () => gatherActiveSessionsLive({ local: false }),
+        });
+        return { sessions: loaded.sessions, remoteDeviceCount: loaded.remoteDeviceCount };
+    }
+    return gatherActiveSessionsLive(opts);
+}
+/**
+ * Live (uncached) gather — the work the daemon / force-refresh path pays once
+ * so other surfaces can share the snapshot. Kept separate so the cache layer
+ * never recursively re-enters itself.
+ */
+async function gatherActiveSessionsLive(opts = {}) {
     const self = machineId();
     // An explicit --host/--device list scopes the view: seed local sessions only
     // when no hosts are named, or when this machine is one of the named targets.
@@ -1057,7 +1233,9 @@ export async function gatherActiveSessions(opts = {}) {
     // remote-host teammate over ssh even for this machine's OWN local gather —
     // "this machine only" must mean zero ssh, not just "skip the cross-machine
     // device fan-out below".
-    const local = shouldIncludeLocal(opts.hosts, self) ? await getActiveSessions({ localOnly: opts.local }) : [];
+    const local = shouldIncludeLocal(opts.hosts, self)
+        ? await getActiveSessions({ localOnly: opts.local })
+        : [];
     for (const s of local)
         if (!s.machine)
             s.machine = self;
@@ -1099,6 +1277,12 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
         ? merged.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
         : merged;
     const sessions = statusFiltered;
+    // Backfill agent version + ticket/PR/label/created onto the live rows from the
+    // historical index (RUSH-2205) — a running process reports none of these, and
+    // an orphan row usually lacks them. Done before both the JSON and human paths
+    // so every consumer (incl. the SSH fan-out's remote --json) sees enriched rows;
+    // transcripts sync across the fleet, so a remote row resolves from the local DB.
+    backfillActiveRowsFromMeta(sessions, loadBackfillMetaFor(sessions));
     if (asJson) {
         // Resolve who is watching each local tmux pane before serializing: `viewingIn`
         // is how a consumer distinguishes a session someone is looking at from one
@@ -1542,8 +1726,13 @@ limitSource) {
     // shorthands fold into --agent, and --device is an alias for --host (both
     // resolve against the same device registry).
     applyAgentShorthands(options);
-    if (options.device && options.device.length > 0) {
-        options.host = [...(options.host ?? []), ...options.device];
+    // --device / --devices both alias --host. A bare `all` / `fleet` sentinel means
+    // "search every peer" — which is already the default — so it resolves to no
+    // explicit host set rather than erroring on a device literally named "all".
+    const deviceTargets = [...(options.device ?? []), ...(options.devices ?? [])]
+        .filter(t => t.toLowerCase() !== 'all' && t.toLowerCase() !== 'fleet');
+    if (deviceTargets.length > 0) {
+        options.host = [...(options.host ?? []), ...deviceTargets];
     }
     // --print-cmd: echo the canonical `ag sessions …` for the given flags and exit.
     // The non-interactive twin of the browser's `y` hotkey — lets an agent compose
@@ -2830,34 +3019,23 @@ export async function resumeSessionInPlace(session) {
     const cwd = session.cwd && fs.existsSync(session.cwd)
         ? session.cwd
         : process.cwd();
-    const resume = buildResumeCommand(session);
-    if (!resume) {
-        console.log(chalk.yellow(`Resume is not supported for ${session.agent} sessions yet. Showing summary instead.`));
-        await renderSession(session, 'summary', {});
-        return;
-    }
+    const resume = buildSessionRecoveryCommand(session);
     console.log(chalk.gray(`Resuming: ${resume.join(' ')} (cwd: ${cwd})`));
-    // Resolve the (possibly version-pinned) launcher up front. On Windows the
-    // agent shim is a `.cmd`/`.ps1` and, under the shell needed to run it (see
-    // spawnResumeCommand), a missing command exits non-zero rather than emitting
-    // an ENOENT `error` event — so detect a removed version here instead of
-    // relying on that event, keeping the fallback working on every OS.
-    // `resume[0]` is an absolute alias path when one exists on disk, so only a bare
-    // name still needs a PATH lookup. Checking existsSync first is what keeps an
-    // isolated install (shims deliberately off PATH) out of the fallback.
-    const launcherFound = path.isAbsolute(resume[0])
-        ? fs.existsSync(resume[0])
-        : !!findExecutable(resume[0]);
-    if (!launcherFound && session.version) {
-        const fallback = buildFallbackCommand(session);
-        if (fallback) {
-            console.log(chalk.gray(`Version ${session.version} is not installed. Resuming with the current version instead...`));
-            await spawnResumeCommand(fallback, cwd);
-            return;
-        }
-    }
     await spawnResumeCommand(resume, cwd);
 }
+/**
+ * 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 function buildSessionRecoveryCommand(session, portable = false) {
+    const args = sessionRecoveryRunArgs(session);
+    if (portable)
+        return ['agents', ...args];
+    const invocation = getAgentsInvocation(args);
+    return [invocation.command, ...invocation.args];
+}
 /**
  * Map a resume argv to the spawn(command, args, {shell}) triple.
  *
@@ -2925,8 +3103,6 @@ function spawnResumeCommand(cmd, cwd) {
  * isolated HOME where the JSONL was written — regardless of which version is
  * currently the default. Falls back to the bare shim when version is unknown.
  *
- * If the versioned binary is missing (version was removed), the ENOENT
- * handler in handlePickedSession retries via buildFallbackCommand.
  */
 /**
  * The agent's own resume invocation, given whichever launcher we resolved.
@@ -2939,6 +3115,8 @@ function resumeArgv(agent, id, launcher) {
         case 'claude': return [launcher, '--resume', id];
         case 'codex': return [launcher, 'resume', id];
         case 'opencode': return [launcher, '--session', id];
+        // Muse interactive resume is a subcommand: `muse resume <uuid>`.
+        case 'muse': return [launcher, 'resume', id];
         default: return null;
     }
 }
@@ -2967,7 +3145,8 @@ export function buildResumeCommand(session) {
         case 'opencode':
             return resumeArgv('opencode', session.id, 'opencode');
         case 'claude':
-        case 'codex': {
+        case 'codex':
+        case 'muse': {
             const cli = AGENTS[session.agent]?.cliCommand ?? session.agent;
             if (session.version) {
                 const alias = versionedAliasIfPresent(session.agent, session.version);
@@ -2990,19 +3169,6 @@ export function buildResumeCommand(session) {
             return null;
     }
 }
-/**
- * Fallback when the pinned version really is gone: the same resume invocation
- * against the current version.
- *
- * This used to spawn `<cli> "/continue <id>"`, feeding a slash command into the
- * TUI as a prompt. Neither CLI has `/continue` — codex documents `/resume` — so
- * the agent received an unrecognised command and the session was not resumed at
- * all. Reusing resumeArgv keeps the two paths from drifting apart again.
- */
-function buildFallbackCommand(session) {
-    const cli = AGENTS[session.agent]?.cliCommand ?? session.agent;
-    return resumeArgv(session.agent, session.id, cli);
-}
 // ---------------------------------------------------------------------------
 // Cloud session source (--cloud)
 // ---------------------------------------------------------------------------
@@ -3073,25 +3239,24 @@ async function runCloudSessions(query, options) {
     // Ensure the SessionMeta points at the local cache path for renderSession.
     await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts, options);
 }
+/** 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 function resolveSessionAgentName(name) {
+    const normalized = name.toLowerCase();
+    if (SESSION_AGENTS.includes(normalized)) {
+        return normalized;
+    }
+    const resolved = resolveAgentName(normalized);
+    if (resolved && SESSION_AGENTS.includes(resolved)) {
+        return resolved;
+    }
+    return fuzzyMatch(normalized, SESSION_AGENTS, FUZZY_PRESETS.agents);
+}
 export function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
     const [name, version] = agentName.split('@', 2);
-    let agent = SESSION_AGENTS.includes(name)
-        ? name
-        : null;
-    if (!agent) {
-        // Aliases and single-typo corrections (cladue -> claude). SESSION_AGENTS
-        // includes ids (rush, hermes) that resolveAgentName doesn't know, so fall
-        // back to fuzzy-matching the session list directly.
-        const resolved = resolveAgentName(name);
-        if (resolved && SESSION_AGENTS.includes(resolved)) {
-            agent = resolved;
-        }
-        else {
-            agent = fuzzyMatch(name, SESSION_AGENTS, FUZZY_PRESETS.agents);
-        }
-    }
+    const agent = resolveSessionAgentName(name);
     if (!agent) {
         console.error(chalk.red(`Unknown agent: ${name}. Use: ${SESSION_AGENTS.join(', ')}`));
         process.exit(1);
@@ -3151,13 +3316,31 @@ function ambiguityHint(byId, completeId) {
         : 'That matched on text, not an id. Pass a session id, or narrow the search.';
 }
 /** Explain a complete-id miss, which no local rephrasing can fix. Echoes the
- * normalized id so a pasted, padded argument doesn't produce an unrunnable hint. */
+ * normalized id so a pasted, padded argument doesn't produce an unrunnable hint.
+ * Used only where NO fleet sweep ran (a `--local` lookup, an `--artifacts`
+ * listing, or a peer answering a parent's sweep) — the fleet-swept miss uses
+ * {@link fleetNotFoundMessage}. Never tells the user to pass `--device`: fleet
+ * search is already the default, so a device flag can't find what the id missed. */
 function notFoundByIdMessage(query) {
+    return [chalk.red(`No session with id ${query.trim()} on this machine.`)];
+}
+/** 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 function fleetNotFoundMessage(query, deviceCount, unreachable) {
     const id = query.trim();
-    return [
-        chalk.red(`No session with id ${id} on this machine.`),
-        chalk.gray(`Search the fleet with: agents sessions ${id} --device <host>`),
-    ];
+    if (deviceCount === 0) {
+        return [
+            chalk.red(`No session with id ${id} on this machine.`),
+            chalk.gray('No other reachable devices to search.'),
+        ];
+    }
+    const searched = `${deviceCount} device${deviceCount === 1 ? '' : 's'}`;
+    const lines = [chalk.red(`No session with id ${id} on this machine or ${searched} searched.`)];
+    if (unreachable.length > 0) {
+        lines.push(chalk.gray(`Unreachable (not searched): ${unreachable.join(', ')}`));
+    }
+    return lines;
 }
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export function filterSessionsByQuery(sessions, query) {
@@ -3380,11 +3563,15 @@ async function renderOneSession(query, mode, scope) {
                 // local not-found message. No FTS fallback either way.
                 if (shouldFanOutForId(query, scope.local)) {
                     const outcome = await resolveSessionAcrossFleet(query, mode, scope.hosts);
-                    if (outcome === 'rendered')
+                    if (outcome.kind === 'rendered')
                         return;
-                    if (outcome === 'conflict')
+                    if (outcome.kind === 'conflict')
                         process.exit(1);
-                    // 'not-found' falls through to the local message below.
+                    // The fleet sweep already ran and found nothing — report what actually
+                    // happened, never "search with --device <host>" (fleet search is the
+                    // default, so a device flag would only re-run the same miss).
+                    fleetNotFoundMessage(query, outcome.deviceCount, outcome.unreachable).forEach(l => console.error(l));
+                    process.exit(1);
                 }
                 notFoundByIdMessage(query).forEach(l => console.error(l));
                 process.exit(1);
@@ -3455,16 +3642,41 @@ function modeFlag(mode) {
     return undefined; // summary — the peer's default render
 }
 const FULL_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * 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 function isDefinitiveMatch(session, selector) {
+    return FULL_SESSION_ID_RE.test(selector) && session.id.toLowerCase() === selector.trim().toLowerCase();
+}
+/**
+ * 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 function selectorAllowsEarlyExit(selector) {
+    return FULL_SESSION_ID_RE.test(selector);
+}
 /** 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 function fleetCandidatesByQuery(rows, query) {
+export function fleetCandidatesByQuery(rows, query, trustResolvedRows = false) {
     // An id selector must still be prefix-filtered defensively against older peers
     // returning content mentioners. Keyword rows, however, were already matched by
     // each peer's own FTS index; the parent does not own that transcript/index and
     // must not re-run metadata-only filtering that could discard a content hit.
-    const matched = looksLikeSessionId(query)
+    const matched = !trustResolvedRows && looksLikeSessionId(query)
         ? resolveSessionQuery(rows, query, { indexFallback: false }).matches
         : rows;
     const byId = new Map();
@@ -3488,6 +3700,14 @@ export function fleetCandidatesByQuery(rows, query) {
 }
 /** Resolve through the canonical metadata+content union used by keyword search. */
 function resolveIndexedMetadataRows(indexed, selector) {
+    const alias = resolveSessionAlias(selector);
+    if (alias.kind === 'resolved') {
+        return resolveSessionQuery(indexed, alias.sessionId, { indexFallback: false }).matches;
+    }
+    if (alias.kind === 'ambiguous') {
+        const ids = new Set(alias.sessionIds.map(id => id.toLowerCase()));
+        return indexed.filter(session => ids.has(session.id.toLowerCase()));
+    }
     return resolveSessionQuery(indexed, selector, { indexFallback: false }).matches;
 }
 /** Fixed peer argv for the metadata resolver. Scope flags compose identically on
@@ -3513,7 +3733,18 @@ export function toolSearchForwardedArgs(argv, hosts) {
  * A full UUID is globally unique, so one exact hit is sufficient even when an
  * unrelated registered device is offline. */
 export function metadataResolveOutcome(localMatches, remote, selector) {
-    const candidates = fleetCandidatesByQuery([...localMatches, ...remote.sessions], selector);
+    // Every peer answered through --resolve-safe-v1, so its native-id row is
+    // already the result of resolving the original selector. Re-filtering by the
+    // selector would discard alias suffixes such as c1f3d813 because the native
+    // UUID intentionally has a different prefix.
+    const candidates = fleetCandidatesByQuery([...localMatches, ...remote.sessions], selector, true);
+    // A full UUID is globally unique, so one exact hit resolves even when an
+    // unrelated registered device is offline. A label is NOT globally unique — a
+    // distinct session may carry the same label on an unreachable peer — so it
+    // stays fail-closed: a unique label auto-resumes only once every peer has
+    // answered (candidates.length === 1 below), and an unreachable peer forces
+    // `partial` rather than guessing. (RUSH-2203: early-exit is UUID-only for the
+    // same reason — see isDefinitiveMatch.)
     if (FULL_SESSION_ID_RE.test(selector) && candidates.length === 1 && candidates[0].id.toLowerCase() === selector.toLowerCase()) {
         return { kind: 'resolved', session: candidates[0].hits[0].session };
     }
@@ -3533,6 +3764,12 @@ export async function resolveSessionMetadataValue(selector, scope = {}, deps = {
     const indexed = includeLocal ? applyScopeFilters(querySessions(), scope) : [];
     const localMatches = resolveIndexedMetadataRows(indexed, selector)
         .map(session => ({ ...session, machine: session.machine || localMachine }));
+    // A full-UUID local hit resolves with ZERO SSH: a UUID is globally unique, so
+    // finding it locally is the whole answer and no peer is dialed. (A label is
+    // NOT resolved local-only here — it can collide with a same-label session on a
+    // peer, so it must consult the fleet; see isDefinitiveMatch, RUSH-2203.) The
+    // local index lookup is synchronous and completes before any fan-out spawns,
+    // so this local hit never waits on a peer.
     if (FULL_SESSION_ID_RE.test(selector)) {
         const localOutcome = metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
         if (localOutcome.kind === 'resolved')
@@ -3542,7 +3779,13 @@ export async function resolveSessionMetadataValue(selector, scope = {}, deps = {
         return metadataResolveOutcome(localMatches, { sessions: [], unreachable: [] }, selector);
     try {
         const forwarded = metadataResolveForwardedArgs(selector, scope);
-        const remote = await deps.gatherRemoteList(forwarded, scope.hosts);
+        // Definitive lookups (full UUID / exact label) opt into early-exit: the
+        // first peer holding the match resolves the sweep and SIGTERMs the rest, so
+        // a fast peer's hit is not bounded by the slowest/unreachable peer. Short-id
+        // prefixes stay all-settle (ambiguity is only known once every peer answers).
+        const remote = await deps.gatherRemoteList(forwarded, scope.hosts, selectorAllowsEarlyExit(selector)
+            ? { isDefinitive: (session) => isDefinitiveMatch(session, selector) }
+            : undefined);
         return metadataResolveOutcome(localMatches, remote, selector);
     }
     catch (error) {
@@ -3586,26 +3829,11 @@ async function resolveSessionMetadata(selector, scope, deps = { gatherRemoteList
     }
     process.stdout.write(serializeResolvedSessionsJson([outcome.session]));
 }
-/**
- * Locate a full session id or short id prefix across the online fleet and render it from the machine
- * that holds it. The local disk already missed; this fans `sessions <id> --json
- * --all` out to every registered online peer (or the explicit `hosts` set),
- * groups the rows to distinct machines, then:
- *
- *   - exactly one logical session → delegate rendering to one peer via `runOnPeer`
- *     (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.
- *
- * 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 async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gatherRemoteList, runOnPeer }) {
     const spinner = isInteractiveTerminal() ? ora('Searching the fleet...').start() : null;
-    let candidates;
+    let candidates = [];
+    let deviceCount = 0;
+    let unreachable = [];
     try {
         // Force whole-index scope (--all): the peer runs in its SSH-login home dir,
         // whose cwd would otherwise silently narrow the lookup and hide the row.
@@ -3613,19 +3841,23 @@ export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gat
         // itself and never re-fans-out (belt-and-suspenders with the parent's
         // AGENTS_SESSIONS_LOCAL, which remote-list also sets on the peer).
         const forwarded = ['sessions', query, '--json', '--all', '--local'];
-        const { sessions } = await deps.gatherRemoteList(forwarded, hosts);
-        candidates = fleetCandidatesByQuery(sessions, query);
+        const remote = await deps.gatherRemoteList(forwarded, hosts, selectorAllowsEarlyExit(query)
+            ? { isDefinitive: (session) => isDefinitiveMatch(session, query) }
+            : undefined);
+        candidates = fleetCandidatesByQuery(remote.sessions, query);
+        deviceCount = remote.deviceCount;
+        unreachable = remote.unreachable;
     }
     catch {
         // A fan-out failure is not an exact resolution — treat as not-found so the
-        // caller prints the honest local message rather than a half-answer.
+        // caller prints the honest message rather than a half-answer.
         candidates = [];
     }
     finally {
         spinner?.stop();
     }
     if (candidates.length === 0)
-        return 'not-found';
+        return { kind: 'not-found', deviceCount, unreachable };
     if (candidates.length > 1) {
         console.error(chalk.red(`Multiple sessions match "${query}" across the fleet:`));
         for (const candidate of candidates) {
@@ -3635,7 +3867,7 @@ export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gat
             console.error(chalk.cyan(`  ${s.shortId}  ${s.id}`) + chalk.gray(`  ${machines}  ${s.agent}${s.version ? ` ${s.version}` : ''}  ${label}`));
         }
         console.error(chalk.gray('Pass a longer ID to narrow it down.'));
-        return 'conflict';
+        return { kind: 'conflict' };
     }
     const candidate = candidates[0];
     const { machine } = candidate.hits[0];
@@ -3651,9 +3883,9 @@ export async function resolveSessionAcrossFleet(query, mode, hosts, deps = { gat
     if (result === 'no-target') {
         console.error(chalk.red(`Session ${candidate.id} is on ${machine}, but it is not a reachable registered device.`));
         console.error(chalk.gray('Register it with `agents devices` or run the command on that machine.'));
-        return 'conflict'; // a definitive answer (found, un-renderable) — do NOT fall to the local not-found line
+        return { kind: 'conflict' }; // a definitive answer (found, un-renderable) — do NOT fall to the local not-found line
     }
-    return 'rendered';
+    return { kind: 'rendered' };
 }
 /** Register the `agents sessions` command with all its options and help text. */
 export function registerSessionsCommands(program) {
@@ -3673,7 +3905,7 @@ export function registerSessionsCommands(program) {
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Widen every non-status filter to "all": every directory (not just this project) and all time (no window cap). Status filters like --active still compose; -a/--device/--since still narrow their axis.')
         .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
-        .option('--teams', 'Include team-spawned sessions (hidden by default)')
+        .option('--team, --teams', 'Include team-spawned sessions (hidden by default)')
         .option('--in-team <name>', "Only this team: the session that spawned it plus (with --teams) its teammates. Spans every directory and all time, since a team's worktrees and history sit outside the default window.")
         .option('--routine', 'Show only sessions archived from routine runs')
         .option('-p, --project <name>', 'Filter by project name (searches across all directories)')
@@ -3711,7 +3943,8 @@ export function registerSessionsCommands(program) {
         .option('--no-live', 'Do not enrich the listing with live status/preview for running sessions')
         .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
         .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)')
-        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
+        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable). `--device all` searches the whole fleet (the default).')
+        .addOption(new Option('--devices <target...>', 'Plural alias for --device (accepts `all`/`fleet`).').hideHelp())
         .option('--fleet', 'With --include tools: query every registered online compute device and merge compact matches')
         .option('--count', 'With one program:<name> tool query: count static occurrences, containing calls, and sessions')
         .option('--browser', 'List browser-profile captures (screenshots, PDFs, recordings, downloads) instead of agent transcripts — alias of `agents browser sessions`')
@@ -3739,7 +3972,7 @@ export function registerSessionsCommands(program) {
       agents sessions --crashed
 
       # --- Session lifecycle (one verb per intent) ---
-      # Jump to a live session (attach its terminal, or open a tab + resume)
+      # Focus a session (attach its living terminal, or recover an ended one)
       agents sessions focus a1b2c3d4
       # Attach only — never fork a copy (old: sessions go)
       agents sessions focus a1b2c3d4 --attach-only
@@ -3791,7 +4024,7 @@ export function registerSessionsCommands(program) {
     `,
         notes: `
       Session lifecycle (pick one verb — they are not synonyms):
-        focus [id]              jump to a live session (attach, or open tab + resume)
+        focus [selector]        attach a living pane, or recover on the origin device
         focus [id] --attach-only  attach only; never fork (replaces sessions go)
         detach <id>             interactive → headless continuation
         attach <id>             headless → interactive in this terminal
@@ -3823,6 +4056,7 @@ export function registerSessionsCommands(program) {
     });
     registerSessionsTailCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
+    registerSessionsForkCommand(sessionsCmd);
     registerSessionsFavoriteCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);