@phnx-labs/agents-cli 1.22.21 → 1.22.23

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

@@ -1,6 +1,8 @@
 import type { Command } from 'commander';
-import { type Packing } from '../lib/terminal/index.js';
-interface ResumeOptions {
+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 +18,21 @@ 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 {};
+/**
+ * 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,18 +14,21 @@ 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, 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 { buildCanonicalResumeCommand } from '../lib/session/resume-command.js';
+import { looksLikeSessionId } from '../lib/session/discover.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)')
@@ -46,6 +49,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,7 +60,8 @@ 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).
@@ -71,6 +79,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');
@@ -118,11 +130,7 @@ async function sessionsResumeAction(query, options) {
     // 2. Split the selection into resumable surfaces and skipped agents (no silent drop).
     const items = [];
     for (const s of chosen) {
-        const command = buildResumeCommand(s);
-        if (!command) {
-            console.log(chalk.yellow(`  skip ${s.shortId} — resume is not supported for ${s.agent} sessions yet`));
-            continue;
-        }
+        const command = buildCanonicalResumeCommand(s.id);
         const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
         items.push({ session: s, cwd, command });
     }
@@ -179,6 +187,37 @@ 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';
 }
@@ -187,7 +226,7 @@ export function resolveResumePacking(options) {
  * (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;
@@ -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 {};