@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/commands/sessions-resume.js

@@ -1,12 +1,14 @@
 /**
- * `agents sessions resume` — multi-select sessions and fan each one out into a
- * terminal surface via the terminal launch engine (src/lib/terminal).
+ * `agents sessions resume` — the one resume surface.
  *
- * Unlike the single-select picker behind bare `agents sessions` (which resumes
- * one session in place), this opens a checkbox picker, then asks where the
- * chosen sessions should resume. By default each session opens in its own tab in
- * the terminal you're in — iTerm / Ghostty / tmux, locally or on a remote host
- * via --host. `--splits` opts into packing two sessions side by side per tab.
+ * - Strict single-session: `sessions resume <id> [prompt]` with optional
+ *   --mode/--headless/--interactive/--cwd/--quiet/--here (formerly top-level
+ *   `agents resume`). Identity resolution + owner-device hop live in resume.ts.
+ * - Multi-select: bare `sessions resume` opens a checkbox picker and fans each
+ *   pick into a terminal tab/split via the terminal launch engine.
+ * - Direct id/alias always takes the strict path; live-pane attach is
+ *   `sessions focus`.
+ * - `--device` opens the terminal surface on the session origin only.
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -25,29 +27,42 @@ import { spawn } from 'node:child_process';
 import { looksLikeSessionId } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
+import { runStrictResume, wantsStrictResume } from './resume.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
     const cmd = sessionsCmd
         .command('resume')
-        .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.')
+        .argument('[query]', 'Session id/tmux alias/label for strict resume, or text that filters the picker')
+        .argument('[prompt]', 'Optional follow-up prompt (strict resume with original harness/version/device)')
+        .description('Resume a session by id (strict), or multi-select history into terminal tabs/splits.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .option('--all', 'Include sessions from every directory (not just current project)')
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
-        .option('--host <alias>', 'Open on the session origin host over SSH; the host must match every selected session')
+        .option('--device <alias>', 'Open on the session origin device over SSH; the device must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
         .option('--tmux', 'Force the tmux backend')
         .option('--vscodium', 'Force the VSCodium agent-terminal backend (swarm-ext)')
         .option('--terminal-app', 'Force macOS Terminal.app (no split support — panes become tabs)')
+        .option('--splits', 'Pack two sessions side by side per tab (default: one tab per session)')
+        .option('-m, --mode <mode>', 'Strict resume: override the recorded launch mode')
+        .option('-i, --interactive', 'Strict resume: interactive even when a prompt is provided')
+        .option('--headless', 'Strict resume: headless (a prompt is required)')
+        .option('--cwd <path>', 'Strict resume: override the recorded working directory')
+        .option('-q, --quiet', 'Strict resume: suppress routing banners')
+        .option('--here', 'Strict resume: run on this machine even if the session belongs to another device')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
-        .option('--attach-only', 'With an id/alias: attach a living pane only — never resume a copy')
-        .option('--splits', 'Pack two sessions side by side per tab (default: one tab per session)');
+        .option('--attach-only', 'With an id/alias: attach a living pane only — never resume a copy');
     setHelpSections(cmd, {
         examples: `
+      # Strict resume by full id (former top-level agents resume)
+      agents sessions resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897
+      agents sessions resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
+      agents sessions resume ag-codex-c1f3d813 --mode edit
+
       # Pick several sessions; each opens in its own tab
       agents sessions resume
 
@@ -65,9 +80,11 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       agents sessions resume --ghostty
       agents sessions resume --vscodium
       agents sessions resume --splits
-      agents sessions resume --host zion --tmux
+      agents sessions resume --device zion --tmux
     `,
         notes: `
+      - Strict path (id/tmux alias/label + optional prompt/--mode/--headless/--here): restores original harness, version, device, account, cwd, and mode. Searches the fleet; a local full-id hit resumes with zero SSH. Replaces the former top-level agents sessions resume.
+      - Attach a live pane without forking: agents sessions focus <id>.
       - This is the ONE verb for getting back in. It detects the state: a live tmux pane is attached, a headless session comes to the foreground, an ended one recovers on its owning device.
       - A UUID/prefix or ag-<agent>-<suffix> alias bypasses the picker. A live alias attaches by name even when the session index cannot attribute it.
       - Retired spellings still work for one release and print the replacement: sessions attach, sessions go, reconnect.
@@ -75,23 +92,40 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       - With no identity selector, space toggles a session, enter confirms, and tab toggles the preview pane.
       - Layout: one tab per session by default. --splits packs session pairs side by side in each tab.
       - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux/--vscodium.
-      - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --host too).
-      - --host <alias> opens the terminal surface on that host only when it is the selected sessions' origin; recovery never migrates a session to another device.
+      - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --device too).
+      - --device <alias> opens the terminal surface on that device only when it is the selected sessions' origin; recovery never migrates a session to another device.
       - Recovery runs on the session's origin device: exact healthy origin uses native resume; otherwise a healthy version of the same harness receives /continue <id>.
     `,
     });
-    cmd.action(async (query, options) => {
-        await sessionsResumeAction(query, options);
+    cmd.action(async (query, prompt, options) => {
+        await sessionsResumeAction(query, prompt, options);
     });
 }
-async function sessionsResumeAction(query, options) {
-    if (!isInteractiveTerminal()) {
-        console.error(chalk.red('sessions resume needs an interactive terminal.'));
-        process.exitCode = 1;
+async function sessionsResumeAction(query, prompt, options) {
+    const strictOpts = {
+        mode: options.mode,
+        interactive: options.interactive,
+        headless: options.headless,
+        cwd: options.cwd,
+        quiet: options.quiet,
+        here: options.here,
+    };
+    // Direct id/alias (or label with prompt/strict flags) → strict resume
+    // (former top-level `agents sessions resume`). `--attach-only` / `--local`
+    // must go through sessions focus so they cannot silently fork a copy
+    // (AGI EXT still shells `sessions resume <id> --local`).
+    if (query && (isDirectResumeSelector(query) || wantsStrictResume(prompt, strictOpts))) {
+        if (resumeUsesLifecycleDispatch(query, prompt, options)) {
+            const hosts = options.device ? [options.device] : [];
+            await dispatchSessionLifecycleInPlace(query.trim(), hosts, !!options.attachOnly, !!options.local);
+            return;
+        }
+        await runStrictResume(query.trim(), prompt, strictOpts);
         return;
     }
-    if (query && isDirectResumeSelector(query)) {
-        await dispatchSessionLifecycleInPlace(query.trim(), options.host ? [options.host] : [], options.attachOnly === true, options.local === true);
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('sessions resume needs an interactive terminal (or pass a session id for strict resume).'));
+        process.exitCode = 1;
         return;
     }
     const { agent, version } = parseAgentFilter(options.agent);
@@ -138,8 +172,8 @@ async function sessionsResumeAction(query, options) {
     }
     if (!chosen || chosen.length === 0)
         return;
-    if (options.host) {
-        const requestedHost = options.host;
+    if (options.device) {
+        const requestedHost = options.device;
         const mismatches = chosen
             .map((session) => resumeHostMismatch(session, requestedHost))
             .filter((message) => message !== null);
@@ -153,7 +187,7 @@ async function sessionsResumeAction(query, options) {
     // 2. Route every selection through the owning device's recovery resolver.
     const items = [];
     for (const s of chosen) {
-        const command = buildSessionRecoveryCommand(s, !!options.host);
+        const command = buildSessionRecoveryCommand(s, !!options.device);
         const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
         items.push({ session: s, cwd, command });
     }
@@ -183,7 +217,7 @@ async function sessionsResumeAction(query, options) {
     // 5b. Fan out through the engine. Full-width tabs are the default for batch
     // recovery; callers can explicitly opt into pairs of side-by-side panes.
     const packing = resolveResumePacking(options);
-    const where = options.host ? `${backend} on ${options.host}` : backend;
+    const where = options.device ? `${backend} on ${options.device}` : backend;
     // Terminal.app has no scriptable split, so its buildSplit opens a tab. Say so
     // when the user actually asked for panes — the layout silently not happening
     // is worse than one line of warning.
@@ -199,7 +233,7 @@ async function sessionsResumeAction(query, options) {
         agent: it.session.agent || undefined,
         sessionId: it.session.id || undefined,
         title: it.session.label || it.session.topic || undefined,
-    })), { backend, host: options.host, packing });
+    })), { backend, host: options.device, packing });
     let opened = 0;
     results.forEach((r, i) => {
         const s = items[i].session;
@@ -220,21 +254,35 @@ export function isDirectResumeSelector(query) {
     const selector = query.trim();
     return looksLikeSessionId(selector) || isAgentTmuxAlias(selector);
 }
-/** Re-enter through the top-level command so fleet routing and harness policy
+/** Re-enter through sessions resume 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]);
+    await spawnCliInPlace(['sessions', '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. */
+/** True when `sessions resume <id> --attach-only|--local` must go through
+ *  `sessions focus` instead of `runStrictResume` (which can fork a copy). */
+export function resumeUsesLifecycleDispatch(query, prompt, options) {
+    if (!query || !isDirectResumeSelector(query))
+        return false;
+    if (!options.attachOnly && !options.local)
+        return false;
+    return !wantsStrictResume(prompt, {
+        mode: options.mode,
+        interactive: options.interactive,
+        headless: options.headless,
+        here: options.here,
+    });
+}
 export async function dispatchSessionLifecycleInPlace(selector, hosts = [], attachOnly = false, local = false) {
     await spawnCliInPlace(buildSessionLifecycleArgs(selector, hosts, attachOnly, local));
 }
 export function buildSessionLifecycleArgs(selector, hosts = [], attachOnly = false, local = false) {
     return [
         'sessions', 'focus', selector,
-        ...hosts.flatMap(host => ['--host', host]),
+        ...hosts.flatMap(host => ['--device', host]),
         ...(attachOnly ? ['--attach-only'] : []),
         ...(local ? ['--local'] : []),
     ];
@@ -257,7 +305,7 @@ export function resumeHostMismatch(session, requestedHost, self = machineId()) {
     const origin = sessionOriginDevice(session, self);
     return sessionRecoveryDestinationMatches(session, requestedHost, self)
         ? null
-        : `Session ${session.shortId} originated on ${origin}; --host ${requestedHost} cannot move recovery to another device.`;
+        : `Session ${session.shortId} originated on ${origin}; --device ${requestedHost} cannot move recovery to another device.`;
 }
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
@@ -274,7 +322,7 @@ export async function resolveBackend(options, ctx, count) {
     if (forced)
         return forced;
     // Remote defaults to tmux (headless, no GUI session assumptions); override with a backend flag.
-    if (options.host)
+    if (options.device)
         return 'tmux';
     const available = availableBackends(ctx);
     if (available.length === 0)

package/dist/commands/sessions-stats.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryResourceUsageStats, resourceUsageCoverage, } from '../lib/session/db.js';
 import { listResources } from '../lib/resources.js';
-import { discoverPlugins } from '../lib/plugins.js';
+import { discoverPlugins } from '../lib/plugins/plugins.js';
 import { setHelpSections } from '../lib/help.js';
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth } from '../lib/session/width.js';
 const DEFAULT_TOP = 20;
@@ -100,7 +100,7 @@ async function statsAction(cmd) {
     const kind = normalizeKind(opts.kind);
     const sinceMs = opts.since ? parseTimeFilter(opts.since) : undefined;
     const top = resolveTop(opts.top);
-    // Warm the incremental index (like `agents cost`) so recent sessions' usage is
+    // Warm the incremental index (like `agents insights cost`) so recent sessions' usage is
     // current before we read. Historical gaps still need the explicit backfill.
     await discoverSessions({ all: true, since: opts.since, limit: 1 });
     const filter = {};

package/dist/commands/sessions.d.ts

@@ -2,9 +2,11 @@ import { type Command } from 'commander';
 import { type ProjectDef } from '../lib/projects.js';
 import type { SessionAgentId, SessionMeta, ViewMode } from '../lib/session/types.js';
 import { type ActiveSession } from '../lib/session/active.js';
+export { activeSessionProjectKey, backfillActiveRowsFromIndex, backfillActiveRowsFromMeta, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson, type BackfillMeta } from '../lib/session/active.js';
+import { loadLocalActiveSessions } from '../lib/session/session-cache.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { type RemoteAgentsJsonParseResult } from '../lib/remote-agents-json.js';
-import { type RunMeta } from '../lib/routines.js';
+import { type RunMeta } from '../lib/scheduling/routines.js';
 import { type PickedSession } from './sessions-picker.js';
 import { type ComputerRunRow } from '../lib/computer/sessions-list.js';
 import { type ToolSearchEnvelope, type ToolProgramCountEnvelope } from '../lib/session/tool-index.js';
@@ -70,7 +72,7 @@ interface SessionsOptions extends SessionFilterOptions {
     /** Force local-only: skip the cross-machine SSH fan-out (both the default
      * listing and --active). */
     local?: boolean;
-    /** --device <target...> — alias for --host; resolves against the device registry. */
+    /** --device <target...> — values from the `--device` flag; 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. */
@@ -142,19 +144,6 @@ 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. */
-export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName'>;
-/**
- * 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;
-/** Add indexed display metadata to active rows for non-renderer consumers. */
-export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): 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,36 +187,6 @@ export declare function liveStatusWord(a: ActiveSession | undefined): string;
  * stays excluded rather than inventing a human who can answer.
  */
 export declare function isAwaitingUser(s: ActiveSession): boolean;
-/**
- * Whether a row belongs in an unqualified `--active` view (RUSH-2336) — the
- * ONE canonical selector every bare-active surface shares: the CLI's grouped
- * table and `--json` (`renderActiveSessions`), the interactive browser's
- * `--active` filter ({@link applyFilters} in `sessions-browser.ts`), `focus`'s
- * attach gate (`isAttachableLiveSession`), and the menubar snapshot
- * ({@link computeMenubarSnapshot}).
- *
- * The live registry deliberately retains terminally-dead AND not-yet-started
- * rows long enough for `--closed` / `--crashed` / `--queued` and recovery to
- * find them. Presence in that registry therefore is not, by itself, evidence
- * that a session is CURRENTLY active. Explicit lifecycle filters bypass this
- * predicate and select those retained rows through {@link matchesLiveStatus}
- * instead — this function only decides the unqualified default.
- *
- *   - `queued` / `closed` / `crashed` are never active here: queued hasn't
- *     started yet, closed/crashed are unconditionally dead. All three stay
- *     reachable through their explicit filter.
- *   - A cloud row carries no local pid at all — it is active on the
- *     provider's own word (`cloudProvider` + `cloudTaskId`), never a
- *     fabricated pid.
- *   - Every other row is a real OS process (terminal/tmux/headless/team). It
- *     is active only when the row names the machine it runs on, carries a
- *     positive pid, AND has POSITIVELY verified that pid is alive
- *     (`pidAlive === true` — not merely "not known dead"). A live orphaned
- *     row, or a live-but-stuck abandoned row, still qualifies this way since
- *     both carry a genuinely alive pid; unknown liveness (an older peer's
- *     row, or a pid that could never be resolved) does not.
- */
-export declare function isRunningLiveSession(s: ActiveSession): boolean;
 /**
  * The tracker/PR ref for a session's dedicated column: the ticket id when known,
  * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
@@ -236,26 +195,36 @@ export declare function isRunningLiveSession(s: ActiveSession): boolean;
 export declare function ticketLabel(s: Pick<SessionMeta, 'ticketId' | 'prNumber'>): string;
 export declare function linkTicketCell(s: Pick<SessionMeta, 'ticketId' | 'prNumber' | 'prUrl'>, label: string): string;
 export declare function linkCwdCell(s: Pick<SessionMeta, 'cwd' | '_remote'>, label: string): string;
+/**
+ * The single project/group key for an active session row (RUSH-2688). It is the
+ * ONE derivation every project-grouped consumer of `--active`/the menubar snapshot
+ * shares, so a session is bucketed the same way everywhere:
+ *
+ *   - A real working dir → its `basename` — the same key SessionMeta derives (see
+ *     discover.ts), so the active view and the history view join identically on
+ *     (ticketId + project).
+ *   - A row with NO local cwd (a cloud task, a provider-run job) → an explicit
+ *     bucket keyed by context: `cloud` for a cloud row, else `other`.
+ *
+ * It never falls back to `kind` (the harness — 'codex', 'claude') or `machine`
+ * (the box it runs on): neither is a project, and letting either stand in for the
+ * key is exactly what leaked a Codex cloud task under a 'codex' group and a bogus
+ * machine label in the menubar. No fallback chain — one explicit bucket.
+ */
 /**
  * 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.
+ * alongside the raw fields, so every active row is joinable. `project` is the
+ * canonical {@link activeSessionProjectKey} — basename(cwd), or an explicit
+ * `cloud`/`other` bucket for a row with no local cwd, never the harness/machine.
  *
  * `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 declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<Omit<ActiveSession, 'viewingIn'> & {
-    ticketId: string | null;
-    project: string | null;
-    prLink: string | null;
-    viewingIn: string | null;
-}>;
 export interface SessionPickerJsonRow extends SessionMeta {
     state: ActiveSession['status'] | 'inactive';
     resumable: boolean;
@@ -351,7 +320,7 @@ export declare function groupSessionsByMachine(sessions: ActiveSession[], localM
  */
 export declare function dedupeByMachineSession(sessions: ActiveSession[]): ActiveSession[];
 /**
- * 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
@@ -378,7 +347,6 @@ export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: s
  * 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 declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /** 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. */
@@ -393,14 +361,14 @@ export declare function parseRemoteComputerSessionRows(stdout: string, machine:
 export declare function gatherRemoteComputerSessionRows(hosts?: string[]): Promise<ComputerRunRow[]>;
 /**
  * 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.
  */
 export declare function shouldIncludeLocal(hosts: string[] | undefined, self: string): boolean;
 /**
- * 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"
@@ -412,9 +380,9 @@ export declare function remoteHostsToDial(hosts: string[] | undefined, self: str
 /**
  * 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
@@ -424,7 +392,7 @@ export declare function remoteHostsToDial(hosts: string[] | undefined, self: str
  * 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 declare function gatherActiveSessions(opts?: {
@@ -434,6 +402,9 @@ export declare function gatherActiveSessions(opts?: {
 }): Promise<{
     sessions: ActiveSession[];
     remoteDeviceCount: number;
+    /** Peer names that went unheard on this gather (RUSH-2507). Undefined when unknown (e.g. a cache hit). */
+    remoteSkipped?: string[];
+    remoteDiscoveryFailed?: boolean;
 }>;
 /** Apply the routine selector to enriched live rows for every non-browser active view. */
 export declare function filterActiveSessionsByRoutine(sessions: ActiveSession[], routine: boolean | string | undefined): ActiveSession[];
@@ -445,8 +416,8 @@ export declare function requestedLiveStatuses(options: SessionsOptions): LiveSta
 /**
  * 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 declare function isBareBrowserListing(options: SessionsOptions, query: string | undefined): boolean;
@@ -907,14 +878,51 @@ export declare function metadataResolveOutcome(localMatches: SessionMeta[], remo
     sessions: SessionMeta[];
     unreachable: string[];
 }, selector: string): MetadataResolveOutcome;
-/** Reusable local-first resolver for `agents run --resume` and `agents resume`.
+/** Injectable dependency for the live-registry cold-miss fallback (RUSH-2682). */
+export type LiveMetadataDeps = {
+    loadActive?: typeof loadLocalActiveSessions;
+};
+/**
+ * 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 declare function computeLocalMetadataMatches(selector: string, scope: {
+    agent?: string;
+    project?: string;
+    local?: boolean;
+    hosts?: string[];
+}, deps?: LiveMetadataDeps): Promise<SessionMeta[]>;
+/**
+ * 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 declare function liveMetadataMatches(selector: string, scope: {
+    agent?: string;
+    project?: string;
+}, self: string, deps?: LiveMetadataDeps): Promise<SessionMeta[]>;
+/** 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 declare function resolveSessionMetadataValue(selector: string, scope?: {
     agent?: string;
     project?: string;
     local?: boolean;
     hosts?: string[];
-}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<MetadataResolveOutcome>;
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'> & LiveMetadataDeps): Promise<MetadataResolveOutcome>;
 /** Resolve one selector to indexed metadata across the fleet without reading or
  * rendering transcript events. A peer answering the parent sweep returns every
  * local candidate; the parent performs the one logical-session uniqueness gate.
@@ -926,7 +934,7 @@ export declare function resolveSessionMetadata(selector: string, scope: {
     project?: string;
     local?: boolean;
     hosts?: string[];
-}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'>): Promise<void>;
+}, deps?: Pick<FleetResolveDeps, 'gatherRemoteList'> & LiveMetadataDeps): Promise<void>;
 /**
  * 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
@@ -934,7 +942,7 @@ export declare function resolveSessionMetadata(selector: string, scope: {
  * 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
+ *     (its transcript and agent binary live there — a local `--device` 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 `{ kind: 'conflict' }`.
@@ -961,4 +969,3 @@ export type FleetResolveResult = {
 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 {};