@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/commands/sessions.js

@@ -13,7 +13,7 @@ import * as path from 'path';
 import { spawn } from 'child_process';
 import { Option } from 'commander';
 import chalk from 'chalk';
-import { truncate, padRight, humanDuration } from '../lib/format.js';
+import { truncate, padRight, humanDuration, formatBytes } from '../lib/format.js';
 import { sanitizeForTerminal, redactSecrets } from '../lib/redact.js';
 import { resolveProjectKey } from '../lib/project-key.js';
 import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
@@ -21,7 +21,8 @@ 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, composeWin32CommandLine } from '../lib/platform/index.js';
-import { getActiveSessions, sessionProcessIsLocal } from '../lib/session/active.js';
+import { getActiveSessions, describeActiveDiscoveryHealth, sessionProcessIsLocal, backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../lib/session/active.js';
+export { activeSessionProjectKey, backfillActiveRowsFromIndex, backfillActiveRowsFromMeta, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } 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';
@@ -33,7 +34,8 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.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, getSessionById, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
+import { findSessionsById, querySessions, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
+import { liveSessionMetas } from '../lib/session/live-metadata.js';
 import { filterTeamSessions, shouldShowTeamSessions, safeTeamText, groupSessionsByTeam, NO_TEAM_GROUP_KEY, } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
@@ -44,13 +46,13 @@ import { sessionOwnerDevice, RESUME_PINNED_ENV } from '../lib/session/resume-own
 import { renderMarkdown } from '../lib/markdown.js';
 import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
 import { getShimsDir } from '../lib/state.js';
-import { listJobs, listJobsWithRuns, listRuns, getRunDir } from '../lib/routines.js';
+import { listJobs, listJobsWithRuns, listRuns, getRunDir } from '../lib/scheduling/routines.js';
 import { formatUsd } from '../lib/pricing/cost.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { itemPicker } from '../lib/picker.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
-import { listInstalledVersions, resolveVersionAliasLoose } from '../lib/versions.js';
-import { getAgentsInvocation } from '../lib/daemon.js';
+import { listInstalledVersions, resolveVersionAliasLoose } from '../lib/installations/versions.js';
+import { getAgentsInvocation } from '../lib/daemon/daemon.js';
 import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker, buildPreview, loadSessionPreviewDigest, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
@@ -68,6 +70,7 @@ import { registerAttachCommand } from './attach.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
 import { registerSessionsRenderCommand } from './sessions-render.js';
+import { registerSessionsShareCommand } from './sessions-share.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
@@ -203,13 +206,6 @@ function resolvePathFilter(query) {
         : query;
     return path.resolve(expanded);
 }
-function formatBytes(n) {
-    if (n < 1024)
-        return `${n} B`;
-    if (n < 1024 * 1024)
-        return `${(n / 1024).toFixed(1)} KB`;
-    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
-}
 async function renderArtifactsForSession(session, listAll, name) {
     const artifacts = discoverArtifacts(session);
     if (name !== undefined) {
@@ -430,66 +426,6 @@ 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;
-        }
-        if (!s.origin && m.origin)
-            s.origin = m.origin;
-        if (!s.routineName && m.routineName)
-            s.routineName = m.routineName;
-    }
-}
-/**
- * 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;
-}
-/** Add indexed display metadata to active rows for non-renderer consumers. */
-export function backfillActiveRowsFromIndex(sessions) {
-    backfillActiveRowsFromMeta(sessions, loadBackfillMetaFor(sessions));
-}
 /**
  * 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
@@ -611,13 +547,6 @@ export function isAwaitingUser(s) {
  *     both carry a genuinely alive pid; unknown liveness (an older peer's
  *     row, or a pid that could never be resolved) does not.
  */
-export function isRunningLiveSession(s) {
-    if (s.status === 'queued' || s.status === 'closed' || s.status === 'crashed')
-        return false;
-    if (s.context === 'cloud')
-        return Boolean(s.cloudProvider) && Boolean(s.cloudTaskId);
-    return Boolean(s.machine) && typeof s.pid === 'number' && s.pid > 0 && s.pidAlive === true;
-}
 /** Width of the live status column — `crashed` is the longest word it renders. */
 const LIVE_STATUS_W = 8;
 /** The colored, space-padded status cell for a listing row (empty when not live). */
@@ -650,29 +579,6 @@ export function linkCwdCell(s, label) {
 function modelLabel(model) {
     return model ? shortenModel(model) : '-';
 }
-/**
- * The row shape `agents sessions --active --json` emits. RUSH-1981: a watcher
- * joins active sessions on ticketId + project, but the raw ActiveSession nests
- * the ticket (`ticket.id`) and carries no `project` at all — so a naive join
- * silently drops every row. Emit both as flat, always-present top-level keys
- * (null when unknown) alongside the raw fields, so every active row is joinable.
- * `project` uses the same derivation SessionMeta does — basename(cwd) (see
- * discover.ts) — so the active view and the history view join identically.
- *
- * `viewingIn` flattens to the same display string the row renderer prints —
- * `'codium tab 3'` / `'detached'` / null — so a consumer can tell a watched
- * session from an orphaned one (its terminal died, the agent is still running)
- * without re-implementing the tmux client lookup.
- */
-export function serializeActiveSessionsForJson(sessions) {
-    return sessions.map((s) => ({
-        ...s,
-        ticketId: s.ticket?.id ?? null,
-        project: s.cwd ? path.basename(s.cwd) : null,
-        prLink: s.pr?.url ?? null,
-        viewingIn: viewingInLabel(s) ?? null,
-    }));
-}
 /** Canonical JSON row consumed by resume pickers and other session UIs. */
 export function serializeSessionPickerRows(sessions, liveSessions, self = machineId()) {
     const liveById = new Map(liveSessions.filter((row) => row.sessionId).map((row) => [row.sessionId, row]));
@@ -1038,7 +944,7 @@ export function dedupeByMachineSession(sessions) {
     return out;
 }
 /**
- * Narrow a gathered live set to the machines an explicit `--host`/`--device`
+ * Narrow a gathered live set to the machines an explicit `--device`
  * scope named. The gather picks which boxes to ASK; this asserts what the answer
  * may contain, and the two are not the same question: a host-dispatched run is
  * reported by the box that dispatched it while executing somewhere else, so
@@ -1094,13 +1000,6 @@ export function mergeLocalFirst(sessions, localMachine) {
  * newline. The single seam shared by the local `--json` path and the
  * `--json --host` remote fan-out so both emit byte-identical row shapes.
  */
-export function serializeSessionsJson(sessions) {
-    const serializable = sessions.map((s) => {
-        const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
-        return rest;
-    });
-    return JSON.stringify(serializable, null, 2) + '\n';
-}
 /** The intentionally small metadata contract emitted by `sessions --resolve`.
  * It includes only launch identity needed to route/resume. Transcript paths,
  * extracted plans, costs, and content stay on the machine that owns them. */
@@ -1329,14 +1228,14 @@ async function enrichTmuxLocators(local, surfaces = []) {
     }
     catch { /* non-fatal */ }
 }
-/** Normalize a `--host`/`--device` token (`alias`, `user@host`, `host.domain`)
+/** Normalize a `--device` token (`alias`, `user@host`, `host.domain`)
  * to the machine id the fan-out and registry key off. */
 function hostToken(h) {
     return normalizeHost(h.split('@').pop() || h);
 }
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
- * included by default; an explicit `--host`/`--device` list scopes the view to
+ * included by default; an explicit `--device` list scopes the view to
  * exactly those machines, so local is dropped unless it is itself named (by
  * alias or `user@host`, matched on the normalized machine id). Exported for
  * unit testing without touching SSH or the live process table.
@@ -1347,7 +1246,7 @@ export function shouldIncludeLocal(hosts, self) {
     return hosts.some(h => hostToken(h) === self);
 }
 /**
- * The peers to dial for an `--active` view. No `--host` → `undefined`, which
+ * The peers to dial for an `--active` view. No `--device` → `undefined`, which
  * tells `gatherRemoteActive` to sweep the registered online devices. An
  * explicit list → exactly those, minus this machine (its sessions come from the
  * local seed, so dialing self would be a wasted SSH and a spurious "unreachable"
@@ -1363,9 +1262,9 @@ export function remoteHostsToDial(hosts, self) {
 /**
  * The fleet-wide live-session set behind every `--active` surface. Local sessions
  * come from `getActiveSessions()` and (unless `--local`) the registered online
- * devices from `ag devices` are folded in over SSH. An explicit `--host`/`--device`
+ * devices from `ag devices` are folded in over SSH. An explicit `--device`
  * list SCOPES the sweep to exactly those machines — the local machine is included
- * only when it is itself named — so `--host` is a filter, not an addition.
+ * only when it is itself named — so `--device` is a filter, not an addition.
  *
  * This is the single gather: the static renderer AND the interactive browser both
  * call it, so the browser can never disagree with `--active --json` about which
@@ -1375,7 +1274,7 @@ export function remoteHostsToDial(hosts, self) {
  * 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
+ * (or `AGENTS_SESSIONS_FORCE_REFRESH=1`) re-gathers live; scoped `--device` lists
  * always gather live so a filter never returns a wrong unscoped snapshot.
  */
 export async function gatherActiveSessions(opts = {}) {
@@ -1403,7 +1302,12 @@ export async function gatherActiveSessions(opts = {}) {
             forceRefresh,
             gather: () => gatherActiveSessionsLive({ local: false }),
         });
-        return { sessions: loaded.sessions, remoteDeviceCount: loaded.remoteDeviceCount };
+        return {
+            sessions: loaded.sessions,
+            remoteDeviceCount: loaded.remoteDeviceCount,
+            remoteSkipped: loaded.remoteSkipped,
+            remoteDiscoveryFailed: loaded.remoteDiscoveryFailed,
+        };
     }
     return gatherActiveSessionsLive(opts);
 }
@@ -1427,6 +1331,8 @@ async function gatherActiveSessionsLive(opts = {}) {
         if (!s.machine)
             s.machine = self;
     let remoteDeviceCount = 0;
+    let remoteSkipped = [];
+    let remoteDiscoveryFailed = false;
     let merged = local;
     if (!opts.local) {
         const remoteHosts = remoteHostsToDial(opts.hosts, self);
@@ -1435,6 +1341,8 @@ async function gatherActiveSessionsLive(opts = {}) {
         if (!opts.hosts?.length || (remoteHosts && remoteHosts.length > 0)) {
             const remote = await gatherRemoteActive(remoteHosts);
             remoteDeviceCount = remote.deviceCount;
+            remoteSkipped = remote.skipped;
+            remoteDiscoveryFailed = remote.discoveryFailed;
             merged = dedupeByMachineSession([...local, ...remote.sessions]);
         }
     }
@@ -1446,8 +1354,36 @@ async function gatherActiveSessionsLive(opts = {}) {
     return {
         sessions: filterActiveSessionsByHostScope(merged, opts.hosts, self),
         remoteDeviceCount,
+        remoteSkipped,
+        remoteDiscoveryFailed,
     };
 }
+/**
+ * Explain an empty `--active` result instead of the old flat
+ * "No active agent sessions." either way (RUSH-2507: a live fleet sweep found
+ * ~41 running agents while this printed the same line as a genuinely idle
+ * fleet). Re-probes local tmux health only now, on the empty path, and names
+ * any remote peer that went unheard rather than silently folding it into
+ * "nothing running".
+ */
+async function describeEmptyActiveDiscovery(opts, remoteSkipped, remoteDiscoveryFailed) {
+    const parts = [];
+    if (!opts.hosts?.length || opts.local) {
+        const health = await describeActiveDiscoveryHealth();
+        if (health.degradedSources.length > 0) {
+            parts.push(`local discovery is degraded (${health.degradedSources.join(', ')} unreachable) — sessions may be hidden, run \`agents doctor\` to diagnose`);
+        }
+    }
+    if (remoteDiscoveryFailed) {
+        parts.push('the device list could not be loaded — no peer was reachable to sweep');
+    }
+    else if (remoteSkipped && remoteSkipped.length > 0) {
+        parts.push(`${remoteSkipped.length} peer(s) went unheard (${remoteSkipped.join(', ')}) — sessions there may be hidden`);
+    }
+    if (parts.length === 0)
+        return 'No active agent sessions.';
+    return `No active agent sessions found, but discovery was degraded: ${parts.join('; ')}.`;
+}
 /**
  * Render the unified active-session view, grouped by machine. Scoping and the
  * fleet sweep live in {@link gatherActiveSessions}; this owns the presentation
@@ -1457,7 +1393,7 @@ async function gatherActiveSessionsLive(opts = {}) {
 async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     const self = machineId();
     const gathered = await gatherActiveSessions(opts);
-    const { remoteDeviceCount } = gathered;
+    const { remoteDeviceCount, remoteSkipped, remoteDiscoveryFailed } = gathered;
     // Backfill agent version, refs, created time, and routine provenance from the
     // historical index. Routine filtering needs that provenance before it narrows
     // the live pool; doing it here also enriches both JSON and human output.
@@ -1489,7 +1425,11 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
         return;
     }
     if (sessions.length === 0) {
-        console.log(chalk.gray(waitingOnly ? 'No sessions waiting on input.' : 'No active agent sessions.'));
+        if (waitingOnly) {
+            console.log(chalk.gray('No sessions waiting on input.'));
+            return;
+        }
+        console.log(chalk.gray(await describeEmptyActiveDiscovery(opts, remoteSkipped, remoteDiscoveryFailed)));
         if (!opts.local && !opts.hosts?.length && remoteDeviceCount === 0)
             printCrossMachineTip();
         return;
@@ -1582,8 +1522,8 @@ function useInteractiveBrowser(options) {
 /**
  * A bare interactive fleet listing — no query, no render/filter flag — that the
  * `runSessionBrowser` picker can represent. The single predicate shared by the
- * bare-browser branch and the `--host` early-return guard so they can't drift:
- * when this holds, an explicit `--host`/`--device` scope is folded into the
+ * bare-browser branch and the `--device` early-return guard so they can't drift:
+ * when this holds, an explicit `--device` scope is folded into the
  * browser (preview-rich, selectable) instead of the legacy per-host raw stream.
  */
 export function isBareBrowserListing(options, query) {
@@ -2022,12 +1962,16 @@ function canonicalSessionsCommand(query, options) {
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
 export async function renderSessionPreview(query, scope) {
     let outcome = await resolveSessionMetadataValue(query, scope);
-    // A just-created transcript may not have reached the incremental index yet.
-    // Keep the indexed path hot, but repair a local cold miss once before saying
-    // it does not exist. This also preserves Claude history-alias discovery.
+    // resolveSessionMetadataValue already consults the live registry for a running
+    // session with no transcript row (RUSH-2682), so a live session resolves above.
+    // This block still repairs the residual case — a session whose transcript is on
+    // disk but not yet indexed (e.g. one that just ended). `waitForScan` makes the
+    // repair honest: when another process holds the scan claim it waits for that
+    // scan instead of returning the stale read. Also preserves Claude history-alias
+    // discovery.
     if (outcome.kind !== 'resolved'
         && (!scope.hosts?.length || shouldIncludeLocal(scope.hosts, machineId()))) {
-        const discovered = applyScopeFilters(await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000 }), scope);
+        const discovered = applyScopeFilters(await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000, waitForScan: true }), scope);
         const localMatches = resolveSessionQuery(discovered, query, { indexFallback: false }).matches
             .map(session => ({ ...session, machine: session.machine || machineId() }));
         const exact = localMatches.find(session => selectorAllowsEarlyExit(query)
@@ -2353,7 +2297,7 @@ limitSource) {
         }
     }
     // Normalize convenience flags before any routing reads them: per-agent
-    // shorthands fold into --agent, and --device is an alias for --host (both
+    // shorthands fold into --agent; --device and --devices (both
     // resolve against the same device registry).
     applyAgentShorthands(options);
     try {
@@ -2364,7 +2308,7 @@ limitSource) {
         process.exitCode = 1;
         return;
     }
-    // --device / --devices both alias --host. A bare `all` / `fleet` sentinel means
+    // --device / --devices values are merged into options.host for internal routing. 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 ?? [])]
@@ -2445,7 +2389,7 @@ limitSource) {
             await runRemoteSessionsJson(options.host);
             return;
         }
-        // A bare interactive `--host`/`--device <box>` listing falls through to the
+        // A bare interactive `--device`/`--device <box>` listing falls through to the
         // fleet browser below, which folds the named host(s) into the same merged,
         // preview-rich, selectable view as the local listing (via gatherRemoteList).
         // A query, a render/filter flag, or a non-interactive caller keeps the legacy
@@ -3797,7 +3741,7 @@ export function formatPickerLabel(s, query, cols = {}, ssh, host = '', bookmarke
 /** Hints rotated above the picker so the flags/features stay discoverable. */
 const PICKER_TIPS = [
     'Tip: narrow with -a/--agent (e.g. -a codex), or --project <name> for another folder.',
-    "Tip: --all searches every directory; -H/--host <machine> folds in another box's sessions.",
+    "Tip: --all searches every directory; -D/--device <machine> folds in another box's sessions.",
     'Tip: just type to fuzzy-search prompts and responses; press space to preview a session.',
     'Tip: --since 2d / --until <date> bound the time window; pass a session id to open it directly.',
 ];
@@ -3865,7 +3809,7 @@ export async function handlePickedSession(picked) {
     if (isIdlessLiveRow(picked.session)) {
         const where = picked.session.machine ? ` on ${picked.session.machine}` : '';
         console.log(chalk.yellow(`This session hasn't reported a session id yet — nothing to open${where}.`));
-        console.log(chalk.gray(`Watch for it with: agents sessions --active${picked.session.machine ? ` --host ${picked.session.machine}` : ''}`));
+        console.log(chalk.gray(`Watch for it with: agents sessions --active${picked.session.machine ? ` --device ${picked.session.machine}` : ''}`));
         return;
     }
     // Reading and resuming are on DIFFERENT machines' terms, and conflating them
@@ -3902,9 +3846,9 @@ export async function resumeOnOwnerIfRemote(session) {
     if (!owner)
         return false;
     console.log(chalk.gray(`Resuming ${session.shortId} on ${owner} over SSH...`));
-    // `agents resume <id>` is the strict single-session path — one pick, one
-    // resume. (`sessions resume <shortId>` would re-open a picker over there.)
-    const rc = await runOnPeer(['resume', session.id], owner, {
+    // `agents sessions resume <id>` is the strict single-session path — one pick, one
+    // resume.
+    const rc = await runOnPeer(['sessions', 'resume', session.id], owner, {
         tty: true,
         env: { [RESUME_PINNED_ENV]: '1' },
     });
@@ -3922,7 +3866,7 @@ export async function resumeOnOwnerIfRemote(session) {
 export async function resumeSessionInPlace(session) {
     // This function is the LOCAL takeover, and every caller is responsible for
     // routing a peer-owned session before it gets here (the picker above,
-    // `agents resume`, `sessions attach`). Reaching it with one anyway means a
+    // `agents sessions resume`, `sessions attach`). Reaching it with one anyway means a
     // caller skipped that step, so refuse rather than start the harness against
     // state this box does not have — the `fs.existsSync(session.cwd)` fallback
     // just below is exactly how that used to pass unnoticed, quietly swapping in
@@ -3930,7 +3874,7 @@ export async function resumeSessionInPlace(session) {
     const owner = sessionOwnerDevice(session);
     if (owner) {
         console.error(chalk.red(`Session ${session.shortId} belongs to ${owner} — it cannot resume on this machine.`));
-        console.error(chalk.gray(`  Resume it there: agents resume ${session.id}`));
+        console.error(chalk.gray(`  Resume it there: agents sessions resume ${session.id}`));
         process.exitCode = 1;
         return;
     }
@@ -4792,14 +4736,60 @@ export function metadataResolveOutcome(localMatches, remote, selector) {
         return { kind: 'ambiguous', candidates };
     return { kind: 'resolved', session: candidates[0].hits[0].session };
 }
-/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
- * Full UUIDs hit the local SQLite index without any SSH fan-out. */
-export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
+/**
+ * Local metadata candidates for a selector: the indexed SQLite rows, plus — when
+ * an id-shaped selector misses the index entirely — the live-session registry
+ * (RUSH-2682).
+ *
+ * Indexing is lazy (it only runs inside `discoverSessions`), so a session THIS
+ * box just started is "running" in `agents sessions --active` minutes before its
+ * transcript reaches the local index. Every id resolver (`preview`, `resume`,
+ * `focus`, and the fan-out peer that answers `--resolve-safe-v1`) therefore
+ * consults the SAME live registry `--active` reads before declaring a running
+ * session non-existent. It reshapes process state the registry already computed;
+ * it parses no transcript and renders nothing. The live path is entered ONLY on a
+ * cold id miss, so an indexed hit keeps its richer row and keyword resolution is
+ * unchanged.
+ */
+export async function computeLocalMetadataMatches(selector, scope, deps = {}) {
     const localMachine = machineId();
     const includeLocal = !scope.hosts?.length || shouldIncludeLocal(scope.hosts, localMachine);
-    const indexed = includeLocal ? indexedRowsForSelector(selector, scope) : [];
-    const localMatches = resolveIndexedMetadataRows(indexed, selector)
-        .map(session => ({ ...session, machine: session.machine || localMachine }));
+    if (!includeLocal)
+        return [];
+    const indexed = resolveIndexedMetadataRows(indexedRowsForSelector(selector, scope), selector);
+    if (indexed.length > 0 || !looksLikeSessionId(selector)) {
+        return indexed.map(session => ({ ...session, machine: session.machine || localMachine }));
+    }
+    const live = await liveMetadataMatches(selector, scope, localMachine, deps);
+    return live.map(session => ({ ...session, machine: session.machine || localMachine }));
+}
+/**
+ * Resolve an id-shaped selector against the local live-session registry
+ * (RUSH-2682). Reads the daemon-warmed active snapshot first (cheap); if that
+ * snapshot predates a just-started session and misses, it forces ONE fresh
+ * gather before conceding, so a session started seconds ago resolves
+ * synchronously. Never throws — a degraded registry read yields no candidates,
+ * so the caller falls through to the ordinary not-found path.
+ */
+export async function liveMetadataMatches(selector, scope, self, deps = {}) {
+    const load = deps.loadActive ?? loadLocalActiveSessions;
+    const match = (metas) => resolveIndexedMetadataRows(applyScopeFilters(metas, scope), selector);
+    try {
+        const cached = liveSessionMetas((await load()).sessions, self, Date.now());
+        const hit = match(cached);
+        if (hit.length > 0)
+            return hit;
+        const fresh = liveSessionMetas((await load({ forceRefresh: true })).sessions, self, Date.now());
+        return match(fresh);
+    }
+    catch {
+        return [];
+    }
+}
+/** Reusable local-first resolver for `agents run --resume` and `agents sessions resume`.
+ * Full UUIDs hit the local SQLite index without any SSH fan-out. */
+export async function resolveSessionMetadataValue(selector, scope = {}, deps = { gatherRemoteList }) {
+    const localMatches = await computeLocalMetadataMatches(selector, scope, deps);
     // 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
@@ -4835,11 +4825,11 @@ export async function resolveSessionMetadataValue(selector, scope = {}, deps = {
  * injectable) so tests can drive this real call site against a fake fan-out
  * instead of only the pure resolver it wraps. */
 export async function resolveSessionMetadata(selector, scope, deps = { gatherRemoteList }) {
-    const localMachine = machineId();
-    const includeLocal = !scope.hosts?.length || shouldIncludeLocal(scope.hosts, localMachine);
-    const indexed = includeLocal ? indexedRowsForSelector(selector, scope) : [];
-    const localMatches = resolveIndexedMetadataRows(indexed, selector)
-        .map(session => ({ ...session, machine: session.machine || localMachine }));
+    // Same local candidate set as resolveSessionMetadataValue, so the peer
+    // answering a fan-out (`--resolve-safe-v1`, NO_FANOUT) surfaces a running
+    // session its own index has not caught yet — the cross-device half of the
+    // RUSH-2682 fix, since the parent's fan-out reads this box's answer.
+    const localMatches = await computeLocalMetadataMatches(selector, scope, deps);
     // A peer is already inside gatherRemoteList. Return all local candidates so
     // the parent can distinguish a fleet-wide unique match from an ambiguity.
     if (process.env[NO_FANOUT_ENV] === '1') {
@@ -4940,7 +4930,7 @@ export function registerSessionsCommands(program) {
         .option('--query <clause>', 'Search text; repeat with --include tools to require distinct matching calls', collectQueryClause, [])
         .option('--resolve <selector>', 'Resolve one full ID, unique prefix, or keyword query to safe session metadata (requires --json; searches the fleet unless --local)')
         .addOption(new Option('--resolve-safe-v1 <selector>').hideHelp())
-        .description('Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active` (alias: `agents roster`).')
+        .description('Find, browse, and read agent conversation transcripts. Live roster: `agents sessions --active`.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .addOption(new Option('--session-version <version>', 'Internal spelling for the public sessions --version filter')
         .hideHelp())
@@ -4989,8 +4979,7 @@ export function registerSessionsCommands(program) {
         .option('--flat', 'Plain flat table (one row per session) instead of the grouped project overview')
         .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). `--device all` searches the whole fleet (the default).')
+        .option('-D, --device <target...>', 'Run this query on remote machine(s) over SSH (device alias from `agents devices`, user@host, or `all` to search the whole fleet; repeatable)')
         .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')
@@ -5075,10 +5064,10 @@ export function registerSessionsCommands(program) {
       agents sessions --resolve d3470b57 --json
 
       # Search another machine's sessions live over SSH (no sync needed)
-      agents sessions "auth bug" --last 3 --host yosemite-s1
+      agents sessions "auth bug" --last 3 --device yosemite-s1
 
       # Fan the same query out across several machines
-      agents sessions --all "deploy script" --host box-a --host box-b
+      agents sessions --all "deploy script" --device box-a --device box-b
     `,
         notes: `
       Session lifecycle — ONE verb gets you back in, it detects the state:
@@ -5090,7 +5079,7 @@ export function registerSessionsCommands(program) {
       - The interactive listing and every live-status flag fold in your other online machines automatically (live over SSH, no sync) — each row is labelled by host, this machine first. Use --local to skip the fan-out; single-id lookups stay local.
       - --all is not a device flag: it widens historical directory and time filters. Fleet collection is already the default. A status flag (--working/--idle/--waiting/--orphan/--crashed/--closed/--abandoned/--queued/--unknown) implies --active; combine status flags for a union.
       - --version <version> requires --agent and is equivalent to --agent <agent@version>.
-      - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
+      - --device runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --in-team matches both ends of the lineage: the session that ran 'agents teams create/add', and (with --teams) that team's teammates. In the interactive list, 't' cycles the same filter over the teams in view.
       - --include and --exclude are mutually exclusive.
       - With --include tools, repeat --query for same-session AND across distinct calls. Fields: tool, program, input, output, status, exit, error.
@@ -5142,8 +5131,7 @@ export function registerSessionsCommands(program) {
         .option('-a, --agent <agent>', 'Narrow the ID to one agent type/version')
         .option('-p, --project <name>', 'Narrow the ID to one project')
         .option('--local', 'Only this machine; do not resolve the ID across the fleet')
-        .option('-H, --host <target...>', 'Resolve only on the named device(s)')
-        .option('--device <target...>', 'Alias for --host')
+        .option('-D, --device <target...>', 'Resolve only on the named device(s)')
         .option('--json', 'Output the session preview as JSON');
     setHelpSections(previewCmd, {
         examples: `
@@ -5186,6 +5174,7 @@ export function registerSessionsCommands(program) {
     registerSessionsInjectCommand(sessionsCmd);
     registerSessionsExportCommand(sessionsCmd);
     registerSessionsRenderCommand(sessionsCmd);
+    registerSessionsShareCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
@@ -5194,31 +5183,6 @@ export function registerSessionsCommands(program) {
     registerSessionsInsightsCommand(sessionsCmd);
     registerSessionsOptimizeCommand(sessionsCmd);
     registerSessionsWatchCommand(sessionsCmd);
-    // Observe-umbrella alias (Phase 3): roster → sessions --active.
-    registerSessionsObserveAliases(program);
-}
-/**
- * `roster` → sessions --active. Registered with the sessions module so the
- * lazy loader for `roster` also registers the real `sessions` command for re-parse.
- */
-function registerSessionsObserveAliases(program) {
-    program
-        .command('roster')
-        .description('Live agent roster (alias of `agents sessions --active`). Who is running right now.')
-        .allowUnknownOption()
-        .allowExcessArguments()
-        .action(async () => {
-        const { expandObserveAlias } = await import('../lib/observe-aliases.js');
-        const rest = process.argv.slice(3);
-        const expanded = expandObserveAlias('roster', rest);
-        if (!expanded) {
-            console.error(chalk.red('Unknown observe alias: roster'));
-            process.exit(1);
-        }
-        if (process.stderr.isTTY)
-            process.stderr.write(chalk.gray(`${expanded.note}\n`));
-        await program.parseAsync(['node', 'agents', ...expanded.argv]);
-    });
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();

package/dist/commands/setup-browser.js

@@ -14,7 +14,7 @@ import { DEFAULT_BROWSER_PROFILE_NAME, createProfile, findFreeProfilePort, getCo
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { defaultBrowserChoice } from './setup-preferences.js';
-const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, or Comet, then re-run `agents setup browser`.\n' +
+const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chromium, Comet, or Arc, then re-run `agents setup browser`.\n' +
     '(Safari and Firefox are not supported — agents browser drives over the Chrome DevTools Protocol.)';
 /**
  * Interactive browser setup. Returns true if a usable default profile exists

package/dist/commands/setup-computer.js

@@ -33,7 +33,7 @@ function openPane(pane) {
 export async function runComputerWizard() {
     if (os.platform() !== 'darwin') {
         console.log(chalk.yellow('`agents setup computer` configures the macOS helper (local control).'));
-        console.log(chalk.dim('On Windows, provision a remote host from a Mac/Linux box instead: `agents computer setup --host <device>`.'));
+        console.log(chalk.dim('On Windows, provision a remote host from a Mac/Linux box instead: `agents computer setup --device <device>`.'));
         return false;
     }
     // 1. Download + verify + install the signed, notarized helper.