@phnx-labs/agents-cli 1.22.22 → 1.22.23

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;
@@ -582,6 +619,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 +667,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 +723,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 {};