@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/lib/session/discover.js

@@ -34,7 +34,7 @@ import { costOfUsage, costOfUsageNoCache } from '../pricing/index.js';
 import { machineForSessionFile } from './origin-machine.js';
 export { machineForSessionFile } from './origin-machine.js';
 import { mapBounded } from '../concurrency.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, getParserStatesForPaths, getDirLedgerForPaths, recordDirScans, recordScans, syncLabels, seedLabelsFromNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, cacheLinearProject, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, getParserStatesForPaths, getDirLedgerForPaths, recordDirScans, recordScans, syncLabels, seedLabelsFromNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, scanInProgressByLivePid, cacheLinearProject, } from './db.js';
 import { buildRunNameMap } from './run-names.js';
 import { resolveLinearApiKey } from '../linear-cache.js';
 import { ToolCallCollector, collectClaudeToolCalls, collectCodexToolCalls, } from './tool-calls.js';
@@ -142,6 +142,12 @@ function dirLedgerDisabled() {
     return v === '1' || v === 'true';
 }
 let cachedOpenClawWorkspaces = null;
+/** Max time a `waitForScan` repair waits for a concurrent scan to settle. */
+const WAIT_FOR_SCAN_TIMEOUT_MS = 2_000;
+const WAIT_FOR_SCAN_POLL_MS = 100;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
 const cachedAgentVersions = new Map();
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
@@ -154,31 +160,81 @@ const cachedAgentVersions = new Map();
  * TTL, no external lock files needed.
  */
 export async function discoverSessions(options) {
+    const { claimed } = await scanSessionsIncremental({
+        agent: options?.agent,
+        onProgress: options?.onProgress,
+    });
+    if (!claimed && options?.waitForScan) {
+        // Lost the single-flight claim to another live process (a foreground
+        // `agents sessions*` or the daemon's index warm). Rather than return the
+        // pre-scan snapshot that just missed, wait (bounded) for that scan to finish
+        // so the read below reflects what it wrote (RUSH-2682 cold-miss repair).
+        await waitForScanToSettle();
+    }
+    return queryIndexedSessions(options, {
+        skipExistenceCheck: options?.skipExistenceCheck ?? false,
+    });
+}
+/**
+ * The write half of {@link discoverSessions}: claim the single-flight scan slot,
+ * incrementally index this host's transcript dirs, and report what was parsed.
+ *
+ * Split out so a caller that only wants the index refreshed — the daemon's warm
+ * tick — can run it WITHOUT the listing query `discoverSessions` ends with. That
+ * query is not free: it applies a cwd filter, runs the `archived_at`-writing
+ * existence check, and can issue a Linear fetch, none of which index anything
+ * (RUSH-2691). Keeping one implementation here is also what stops the tick and
+ * the foreground path from drifting apart.
+ */
+export async function scanSessionsIncremental(options) {
     // Touch the DB so the schema is ready and connection is cached for this run.
     getDB();
     const agents = options?.agent ? [options.agent] : SESSION_AGENTS;
     const onProgress = options?.onProgress;
-    if (tryClaimScan(process.pid)) {
-        try {
-            // Bounded + staggered instead of a single Promise.all: scanning every
-            // agent's dotfile dir (~/.claude, ~/.codex, ~/.gemini, …) simultaneously
-            // reads to behavioral EDR (CrowdStrike Falcon) as a ransomware-style bulk
-            // file-enumeration sweep. Same dirs, same results — just not all at once.
-            await scanAgentsBounded(agents, agent => dispatchAgentScan(agent, onProgress));
-            await scanAgentsBounded(agents, agent => scanRoutineArchivesIncremental(agent, onProgress));
-            // Seed labels from `agents run --name` handles onto the freshly-scanned
-            // rows by id. Runs AFTER the per-agent scans (which applied agent-generated
-            // titles via syncLabels), so a real title always wins and the seed only
-            // backfills sessions that would otherwise be unnamed.
-            seedLabelsFromNames(buildRunNameMap());
-        }
-        finally {
-            releaseScan(process.pid);
-        }
+    if (!tryClaimScan(process.pid))
+        return { claimed: false, scanned: 0 };
+    // `parsed` climbs monotonically within one scanner run, so the last value per
+    // (phase, agent) is that scanner's total. Phase-keyed because the dotfile scan
+    // and the routine-archive scan both report under the same agent id.
+    const parsedByPhaseAgent = new Map();
+    const track = (phase) => (p) => {
+        parsedByPhaseAgent.set(`${phase}\0${p.agent}`, p.parsed);
+        onProgress?.(p);
+    };
+    try {
+        // Bounded + staggered instead of a single Promise.all: scanning every
+        // agent's dotfile dir (~/.claude, ~/.codex, ~/.gemini, …) simultaneously
+        // reads to behavioral EDR (CrowdStrike Falcon) as a ransomware-style bulk
+        // file-enumeration sweep. Same dirs, same results — just not all at once.
+        await scanAgentsBounded(agents, agent => dispatchAgentScan(agent, track('dotfiles')));
+        await scanAgentsBounded(agents, agent => scanRoutineArchivesIncremental(agent, track('routines')));
+        // Seed labels from `agents run --name` handles onto the freshly-scanned
+        // rows by id. Runs AFTER the per-agent scans (which applied agent-generated
+        // titles via syncLabels), so a real title always wins and the seed only
+        // backfills sessions that would otherwise be unnamed.
+        seedLabelsFromNames(buildRunNameMap());
     }
-    return queryIndexedSessions(options, {
-        skipExistenceCheck: options?.skipExistenceCheck ?? false,
-    });
+    finally {
+        releaseScan(process.pid);
+    }
+    let scanned = 0;
+    for (const n of parsedByPhaseAgent.values())
+        scanned += n;
+    return { claimed: true, scanned };
+}
+/**
+ * Poll until no live process holds the scan claim, or the bound elapses
+ * (RUSH-2682). Bounded so a wedged/slow scan can never hang a foreground preview.
+ * Exported for the cold-miss repair test.
+ */
+export async function waitForScanToSettle(timeoutMs = WAIT_FOR_SCAN_TIMEOUT_MS, pollMs = WAIT_FOR_SCAN_POLL_MS) {
+    const deadline = Date.now() + timeoutMs;
+    while (scanInProgressByLivePid()) {
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(pollMs);
+    }
+    return true;
 }
 /** Read the current SQLite snapshot without scanning or parsing transcript files. */
 export async function queryIndexedSessions(options, indexedOptions = {}) {
@@ -202,6 +258,38 @@ export async function queryIndexedSessions(options, indexedOptions = {}) {
     }
     return scopeToManaged(sessions, agents, options);
 }
+/**
+ * Resolve a full-or-partial session id against the LOCAL SQLite index only.
+ *
+ * A plain WAL read through `queryIndexedSessions` — same origin-machine
+ * attribution and managed scoping every indexed read gets — with NO incremental
+ * discovery scan (so none of `tryClaimScan`/`releaseScan`'s `BEGIN IMMEDIATE`
+ * writer lock) and NO fleet SSH fan-out. This is the crash-restart storm path
+ * (RUSH-2477): dozens of `sessions resume <id>` at once for a known local id must
+ * each be a cheap read, never a writer-lock contender or a dial into the
+ * not-yet-up tailnet. Exact id first, then prefix (matching `findSessionsById`),
+ * so a complete id never also drags in its prefix siblings. Returns `[]` on a
+ * genuine local miss, leaving the caller to fall back to the fleet resolver.
+ *
+ * The existence check is left ON (`skipExistenceCheck: false`), exactly as the old
+ * `discoverSessions` path and `findSessionsById` do (RUSH-2436): it KEEPS a
+ * file-gone session whose user turns still live in `session_text` (flagged
+ * archived) and SUPPRESSES a contentless phantom — so a phantom id misses here and
+ * falls through to the fleet resolver, instead of resolving to a row with no real
+ * transcript to resume. For a present transcript — the storm's actual case, since
+ * the crashed tabs' files are on disk — the check does no writes, so the lock-free
+ * guarantee holds; it only writes to (un)archive a genuinely missing or resurrected
+ * file, which is not the 20-at-once resume path.
+ */
+export async function resolveIndexedSessionById(idQuery) {
+    const q = idQuery.trim();
+    if (!q)
+        return [];
+    const exact = await queryIndexedSessions({ all: true, unbounded: true, idExact: q }, { resolveLinear: false, skipExistenceCheck: false });
+    if (exact.length > 0)
+        return exact;
+    return queryIndexedSessions({ all: true, unbounded: true, idPrefix: q }, { resolveLinear: false, skipExistenceCheck: false });
+}
 const linearProjectCache = new Map();
 async function resolveLinearProjects(sessions) {
     const apiKey = resolveLinearApiKey();
@@ -310,8 +398,8 @@ function dispatchAgentScan(agent, onProgress) {
         case 'codex': return scanCodexIncremental(onProgress);
         case 'gemini': return scanGeminiIncremental(onProgress);
         case 'antigravity': return scanAntigravityIncremental(onProgress);
-        case 'opencode': return scanOpenCodeIncremental();
-        case 'openclaw': return scanOpenClawIncremental();
+        case 'opencode': return scanOpenCodeIncremental(onProgress);
+        case 'openclaw': return scanOpenClawIncremental(onProgress);
         case 'rush': return scanRushIncremental(onProgress);
         case 'hermes': return scanHermesIncremental(onProgress);
         case 'kimi': return scanKimiIncremental(onProgress);
@@ -418,6 +506,8 @@ function buildQueryOptions(options, agents, opts) {
         skipExistenceCheck: options?.skipExistenceCheck,
         skill: options?.skill,
         plugin: options?.plugin,
+        idExact: options?.idExact,
+        idPrefix: options?.idPrefix,
     };
 }
 /**
@@ -1940,7 +2030,7 @@ function openCodeSessionStamp(times, bytes, dbScan) {
     return { fileMtimeMs: known.length === 0 ? 0 : Math.floor(Math.max(...known)), fileSize: size };
 }
 /** Scan OpenCode sessions from its SQLite database when the DB file has changed. */
-async function scanOpenCodeIncremental() {
+async function scanOpenCodeIncremental(onProgress) {
     if (!fs.existsSync(OPENCODE_DB))
         return;
     const stat = safeStatSync(OPENCODE_DB);
@@ -2135,6 +2225,12 @@ async function scanOpenCodeIncremental() {
             entries.push({ meta, content: topic || '', scan });
         }
         upsertSessionsBatch(entries);
+        // Report what this scan indexed. OpenCode is one SQLite DB rather than N
+        // transcript files, so the whole batch lands as a single progress emit —
+        // enough for the daemon's warm tick to count it (RUSH-2691); without it a
+        // tick whose only changed sessions were OpenCode's reported 0 and logged
+        // nothing, the same silent-success class this tick exists to remove.
+        onProgress?.({ agent: 'opencode', parsed: entries.length, total: entries.length });
         // Stamp the OpenCode DB itself so we can short-circuit on the next run.
         recordScans([{ filePath: OPENCODE_DB, scan: currentScan }]);
     }
@@ -2154,7 +2250,7 @@ async function scanOpenCodeIncremental() {
 // OpenClaw
 // ---------------------------------------------------------------------------
 /** Scan active OpenClaw channels and cron jobs via the openclaw CLI. */
-async function scanOpenClawIncremental() {
+async function scanOpenClawIncremental(onProgress) {
     // Check if openclaw is installed — silently skip if not. `which` is POSIX-only
     // (Windows resolves PATH with `where`), so a bare `which` throws ENOENT on every
     // Windows run and silently disabled the entire OpenClaw scan there — its sessions
@@ -2247,6 +2343,15 @@ async function scanOpenClawIncremental() {
         /* cron command failed */
     }
     upsertSessionsBatch(entries);
+    // Deliberately NO onProgress emit, unlike every other scanner (RUSH-2691).
+    // This one cannot report a delta: its gate is a 60s TTL (not a store stamp),
+    // `scan` above stamps a fresh `now` on every entry every run, and `entries` is
+    // the CURRENT INVENTORY — running channels plus cron jobs — rebuilt from
+    // scratch each pass. Emitting entries.length would report "how many openclaw
+    // things exist", re-counted every 60s forever, which is a worse lie than
+    // silence: the warm tick's number means "transcripts parsed this scan". Giving
+    // OpenClaw a real per-entry stamp is tracked separately; until then it
+    // contributes 0 and the docblock on IncrementalScanResult says so.
     db.prepare(`INSERT OR REPLACE INTO meta (key, value) VALUES ('openclaw_last_scan_ms', ?)`).run(String(Date.now()));
 }
 /** Incrementally re-scan changed Rush session files and upsert into the DB. */

package/dist/lib/session/fork.js

@@ -80,7 +80,7 @@ export function forkSession(source, opts = {}) {
     // Label sidecar (seeds the DB label; survives rescans until an agent title
     // supersedes it), mirroring `agents run --name`.
     recordRunName({ sessionId: newId, name: label, agent: source.agent, cwd: source.cwd });
-    // Register the new session so it resolves immediately (by `agents resume`,
+    // Register the new session so it resolves immediately (by `agents sessions resume`,
     // `agents sessions`, etc.) without waiting for the next scan.
     const stamp = opts.now ?? new Date().toISOString();
     const meta = {

package/dist/lib/session/inject.d.ts

@@ -9,7 +9,7 @@
  * engine stays agnostic of how a target was discovered.
  */
 import type { ReplyRail } from './provenance.js';
-import type { InjectTarget } from '../terminal/inject.js';
+import type { InjectTarget } from '../terminal/index.js';
 /**
  * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
  * are externally addressable (provenance.ts:143-149); a null rail yields null and

package/dist/lib/session/insights.d.ts

@@ -2,7 +2,7 @@
  * Behavioural facets of a coding session, and the cross-session rollup built from them.
  *
  * This is the engine behind `agents insights`. It answers "how do you work" rather than
- * "what did you spend" (`agents cost`) or "what shipped" (`agents output`), and it is
+ * "what did you spend" (`agents insights cost`) or "what shipped" (`agents insights output`), and it is
  * the only surface that splits any of it by the account that produced the work.
  *
  * Everything here is a pure function of a parsed `SessionEvent[]`, so it is testable

package/dist/lib/session/insights.js

@@ -2,7 +2,7 @@
  * Behavioural facets of a coding session, and the cross-session rollup built from them.
  *
  * This is the engine behind `agents insights`. It answers "how do you work" rather than
- * "what did you spend" (`agents cost`) or "what shipped" (`agents output`), and it is
+ * "what did you spend" (`agents insights cost`) or "what shipped" (`agents insights output`), and it is
  * the only surface that splits any of it by the account that produced the work.
  *
  * Everything here is a pure function of a parsed `SessionEvent[]`, so it is testable

package/dist/lib/session/live-metadata.d.ts

@@ -0,0 +1,15 @@
+import { type SessionMeta } from './types.js';
+import type { ActiveSession } from './active.js';
+/**
+ * Reshape one live `ActiveSession` into a `SessionMeta` candidate for the id
+ * resolver. Returns `null` for a row that cannot back a durable session — no
+ * `sessionId`, or a `kind` that is not a session-tracked harness (cloud/team
+ * rows without a real agent transcript). Pure: the caller supplies `self` (the
+ * local machine id) and `nowMs` so the row is deterministic and testable.
+ */
+export declare function activeSessionToSessionMeta(active: ActiveSession, self: string, nowMs: number): SessionMeta | null;
+/**
+ * Map every eligible live session to a `SessionMeta` candidate. Ineligible rows
+ * (no id, non-agent kind) are dropped. Order follows the input.
+ */
+export declare function liveSessionMetas(active: ActiveSession[], self: string, nowMs: number): SessionMeta[];

package/dist/lib/session/live-metadata.js

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Live-registry → SessionMeta bridge (RUSH-2682)
+// ---------------------------------------------------------------------------
+//
+// A session the live registry (`getActiveSessions`) already knows about can be
+// minutes ahead of the transcript index on the SAME box: indexing is lazy and
+// only runs inside `discoverSessions`, so a session this machine JUST started is
+// "running" in `agents sessions --active` while `agents sessions preview <id>`
+// answers "No session matching" until an unrelated `agents sessions*` call
+// happens to scan (measured 7.6 min blind on zion, agents-cli 1.22.39).
+//
+// This module converts a running `ActiveSession` into a `SessionMeta` candidate
+// so the id resolver behind `preview` / `resume` / `focus` can resolve and render
+// a running session with no transcript row yet, instead of claiming it does not
+// exist. It parses no transcript and renders nothing — it only reshapes process
+// state the live registry already computed. When the transcript IS on disk, the
+// synthesized row carries its path, so the downstream `buildPreview` renders the
+// real digest; otherwise it renders the header + a "not indexed here" note.
+import { deriveShortId } from './short-id.js';
+import { isSessionTrackedAgent } from './types.js';
+/**
+ * Reshape one live `ActiveSession` into a `SessionMeta` candidate for the id
+ * resolver. Returns `null` for a row that cannot back a durable session — no
+ * `sessionId`, or a `kind` that is not a session-tracked harness (cloud/team
+ * rows without a real agent transcript). Pure: the caller supplies `self` (the
+ * local machine id) and `nowMs` so the row is deterministic and testable.
+ */
+export function activeSessionToSessionMeta(active, self, nowMs) {
+    const id = active.sessionId;
+    if (!id)
+        return null;
+    if (!isSessionTrackedAgent(active.kind))
+        return null;
+    const startedMs = active.startedAtMs ?? nowMs;
+    const lastMs = active.lastActivityMs ?? startedMs;
+    return {
+        id,
+        shortId: deriveShortId(id),
+        agent: active.kind,
+        timestamp: new Date(startedMs).toISOString(),
+        lastActivity: new Date(lastMs).toISOString(),
+        // An empty file path is honest — a just-created session may have no
+        // transcript on disk yet, and `buildPreview` renders the header + a live
+        // note for that case rather than trying to parse a missing file.
+        filePath: active.sessionFile ?? '',
+        cwd: active.cwd,
+        project: active.project ?? undefined,
+        label: active.label,
+        topic: active.topic,
+        version: active.version,
+        messageCount: undefined,
+        // The row runs HERE — the local live registry is machine-local, so a match
+        // resolves without an SSH hop back to a peer.
+        machine: active.machine ?? self,
+        ticketId: active.ticket?.id,
+        prUrl: active.pr?.url,
+        prNumber: active.pr?.number,
+        worktreeSlug: active.worktree?.slug,
+        gitBranch: active.worktree?.branch,
+        origin: active.origin,
+        routineName: active.routineName,
+    };
+}
+/**
+ * Map every eligible live session to a `SessionMeta` candidate. Ineligible rows
+ * (no id, non-agent kind) are dropped. Order follows the input.
+ */
+export function liveSessionMetas(active, self, nowMs) {
+    const out = [];
+    for (const a of active) {
+        const meta = activeSessionToSessionMeta(a, self, nowMs);
+        if (meta)
+            out.push(meta);
+    }
+    return out;
+}

package/dist/lib/session/migrate-targets.d.ts

@@ -18,7 +18,7 @@ import type { DeviceStats, Headroom } from '../devices/health.js';
 import type { CrabboxBox } from '../crabbox/cli.js';
 /** A machine the current session could be relocated onto. */
 export interface MigrateTarget {
-    /** The `--host` value: a host/device name, or a warm box slug for ephemeral. */
+    /** The `--device` value: a host/device name, or a warm box slug for ephemeral. */
     name: string;
     /** Where the target comes from — a fleet host/device, or a warm crabbox box. */
     kind: 'fleet' | 'ephemeral';

package/dist/lib/session/recovery.d.ts

@@ -1,4 +1,4 @@
-import { type RotateCandidate } from '../rotate.js';
+import { type RotateCandidate } from '../accounting/rotate.js';
 import type { AgentId } from '../types.js';
 import type { SessionMeta } from './types.js';
 export type SessionRecoveryTarget = {

package/dist/lib/session/recovery.js

@@ -4,8 +4,8 @@ import { AGENTS, agentConfigDirName } from '../agents.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { nativeResume } from '../exec.js';
 import { machineId, normalizeHost } from '../machine-id.js';
-import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../rotate.js';
-import { getVersionHomePath } from '../versions.js';
+import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../accounting/rotate.js';
+import { getVersionHomePath } from '../installations/versions.js';
 export class SessionRecoveryError extends Error {
     constructor(message) {
         super(message);

package/dist/lib/session/remote-active.d.ts

@@ -19,10 +19,19 @@ export interface RemoteActiveResult {
     sessions: ActiveSession[];
     /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
     deviceCount: number;
+    /**
+     * Peer device names that were unreachable, timed out, or lacked the CLI —
+     * distinct from a peer that answered with zero sessions. Named so an empty
+     * fleet-wide result can say WHICH peers went unheard rather than reading
+     * identical to "the fleet is genuinely idle" (RUSH-2507).
+     */
+    skipped: string[];
+    /** True when the device list itself could not be loaded — no peer was even attempted. */
+    discoveryFailed: boolean;
 }
 /**
  * Gather active sessions from other machines. With an explicit `hosts` list
- * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * (from `--device`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. Results from all peers run in parallel and are flattened.
  * `opts.quiet` suppresses the per-device stderr line for callers that report

package/dist/lib/session/remote-active.js

@@ -7,7 +7,7 @@
  * it came from so the renderer can bucket by computer.
  *
  * Peers are the registered, online devices from `ag devices` (or an explicit
- * `--host` list). `--local` on the remote invocation is critical: it stops the
+ * `--device` list). `--local` on the remote invocation is critical: it stops the
  * peer from fanning out to *its* devices, so the sweep never recurses.
  *
  * A dead or slow host is skipped with a stderr note, never fatal — one asleep
@@ -67,7 +67,7 @@ export function parseRemoteActive(stdout, machine) {
 }
 /**
  * Gather active sessions from other machines. With an explicit `hosts` list
- * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * (from `--device`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. Results from all peers run in parallel and are flattened.
  * `opts.quiet` suppresses the per-device stderr line for callers that report
@@ -81,5 +81,10 @@ export async function gatherRemoteActive(hosts, opts) {
         parse: parseRemoteActive,
         quiet: opts?.quiet,
     });
-    return { sessions: result.items, deviceCount: result.deviceCount };
+    return {
+        sessions: result.items,
+        deviceCount: result.deviceCount,
+        skipped: result.skipped,
+        discoveryFailed: result.discoveryFailed,
+    };
 }

package/dist/lib/session/remote-bundle.d.ts

@@ -7,6 +7,6 @@ export interface RemotePullResult {
  * Run `agents sessions export …exportArgs --stdout` on each host and parse the
  * streamed bundle. A host that fails (unreachable, remote error, bad output) is
  * collected in `errors` and skipped — one asleep peer never aborts the pull.
- * `exportArgs` must NOT contain --host (the remote export runs for itself only).
+ * `exportArgs` must NOT contain --device (the remote export runs for itself only).
  */
 export declare function pullBundlesFromHosts(hosts: string[], exportArgs: string[]): Promise<RemotePullResult>;

package/dist/lib/session/remote-bundle.js

@@ -1,6 +1,6 @@
 /**
  * Multi-device session transfer over the EXISTING SSH fleet transport
- * (RUSH-1712) — no R2, no daemon. `agents sessions export --host <h>` and
+ * (RUSH-1712) — no R2, no daemon. `agents sessions export --device <h>` and
  * `agents sessions import --from-host <h>` both run `agents sessions export
  * … --stdout` ON the peer and stream the bundle back over the same SSH path the
  * cross-machine listing already uses (resolveExplicitTargets + ssh-exec), then
@@ -31,7 +31,7 @@ function remoteAgentsCommand(args, os) {
  * Run `agents sessions export …exportArgs --stdout` on each host and parse the
  * streamed bundle. A host that fails (unreachable, remote error, bad output) is
  * collected in `errors` and skipped — one asleep peer never aborts the pull.
- * `exportArgs` must NOT contain --host (the remote export runs for itself only).
+ * `exportArgs` must NOT contain --device (the remote export runs for itself only).
  */
 export async function pullBundlesFromHosts(hosts, exportArgs) {
     const targets = await resolveExplicitTargets(hosts);

package/dist/lib/session/remote-list.d.ts

@@ -60,7 +60,7 @@ export interface RemoteListResult {
 export declare function isAutomaticSessionPeer(d: DeviceProfile, self: string): boolean;
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
- * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * (from `--device`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. `forwardedArgs` are the caller's own sessions args (query + filters,
  * already `--json`) so every peer returns the same slice this machine asked for.
@@ -113,22 +113,33 @@ export declare function resolvePeerTarget(machine: string): Promise<{
     target: string;
     os?: string;
 } | undefined>;
+/**
+ * Fetch one remote session's preview digest from its owning peer — the data
+ * behind the picker pane for a `_remote` row, whose transcript file this
+ * machine cannot parse. Runs the peer's own `agents sessions preview <id>
+ * --local --json` (the same envelope `agents sessions preview` already
+ * delegates to for a remote id) and returns its `preview` object, verbatim and
+ * UNSANITIZED — the caller owns scrubbing peer-supplied strings before any of
+ * them reach a TTY. Undefined on every failure: unregistered machine, SSH
+ * error, timeout, version-skewed peer with no `--json` preview envelope.
+ */
+export declare function fetchPeerPreviewDigest(sessionId: string, machine: string, timeoutMs?: number): Promise<unknown | undefined>;
 /**
  * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
  * stdio). `args` is the full arg vector after the binary — callers pass e.g.
  * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
  * picked session lives on another machine: its transcript and agent binary are
  * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
- * not via a local `--host` hop, which would discover locally and dead-end for a
+ * not via a local `--device` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
  *
  * `opts.env` adds variables to the remote command. It deliberately does NOT
- * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * carry `AGENTS_FLEET_REMOTE` the way the `--device` passthrough does: that marker
  * gates consent-sensitive actions on the far side
  * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
  * that would inherit it for its whole life — `agents browser start` inside it
- * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * would then be refused as a cross-machine drive. A one-shot `--device` command
  * can carry the marker; a session cannot.
  */
 export declare function runOnPeer(args: string[], machine: string, opts?: {

package/dist/lib/session/remote-list.js

@@ -523,22 +523,59 @@ export async function resolvePeerTarget(machine) {
     }
     return undefined;
 }
+/** Interactive ceiling for a picker-driven peer preview fetch. Tighter than the
+ * fan-out's 60s: the user is arrowing through rows, and a peer that can't
+ * answer a one-session digest in this window should degrade to the metadata
+ * card rather than hold a "fetching…" pane open. */
+const PEER_PREVIEW_TIMEOUT_MS = 15_000;
+/**
+ * Fetch one remote session's preview digest from its owning peer — the data
+ * behind the picker pane for a `_remote` row, whose transcript file this
+ * machine cannot parse. Runs the peer's own `agents sessions preview <id>
+ * --local --json` (the same envelope `agents sessions preview` already
+ * delegates to for a remote id) and returns its `preview` object, verbatim and
+ * UNSANITIZED — the caller owns scrubbing peer-supplied strings before any of
+ * them reach a TTY. Undefined on every failure: unregistered machine, SSH
+ * error, timeout, version-skewed peer with no `--json` preview envelope.
+ */
+export async function fetchPeerPreviewDigest(sessionId, machine, timeoutMs = PEER_PREVIEW_TIMEOUT_MS) {
+    const peer = await resolvePeerTarget(machine);
+    if (!peer)
+        return undefined;
+    const cmd = remoteListCommand(['sessions', 'preview', sessionId, '--local', '--json'], peer.os);
+    const capture = await sshCapture(peer.target, cmd, timeoutMs);
+    if (capture.code !== 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(stripClixml(capture.stdout));
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const preview = parsed.preview;
+    if (!preview || typeof preview !== 'object' || Array.isArray(preview))
+        return undefined;
+    return preview;
+}
 /**
  * Run `agents <args>` ON a peer over SSH, attached to this terminal (inherited
  * stdio). `args` is the full arg vector after the binary — callers pass e.g.
  * `['sessions', id, '--markdown']` or `['sessions', 'resume', id]`. Used when a
  * picked session lives on another machine: its transcript and agent binary are
  * there, so both reading (no TTY) and resuming (TTY) must execute on the peer —
- * not via a local `--host` hop, which would discover locally and dead-end for a
+ * not via a local `--device` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
  *
  * `opts.env` adds variables to the remote command. It deliberately does NOT
- * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * carry `AGENTS_FLEET_REMOTE` the way the `--device` passthrough does: that marker
  * gates consent-sensitive actions on the far side
  * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
  * that would inherit it for its whole life — `agents browser start` inside it
- * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * would then be refused as a cross-machine drive. A one-shot `--device` command
  * can carry the marker; a session cannot.
  */
 export async function runOnPeer(args, machine, opts = {}) {

package/dist/lib/session/remote.d.ts

@@ -6,11 +6,11 @@
  */
 export declare function shellQuote(s: string): string;
 /**
- * Strip the `--host`/`-H` flag (and its value) from a raw `agents sessions` argv,
+ * Strip the `--device`/`-D` flag (and its value) from a raw `agents sessions` argv,
  * leaving the args to forward to the remote unchanged. The remote runs the same
  * binary, so every other flag (`--since`, `--last`, `--json`, query, …) carries
- * over for free. Handles every form commander accepts: `--host h`, `--host=h`,
- * `-H h`, `-H=h`, and the glued short form `-Hh`.
+ * over for free. Handles every form commander accepts: `--device h`, `--device=h`,
+ * `-D h`, `-D=h`, and the glued short form `-Dh`.
  *
  * @param argv full process argv; the sessions args begin at index 2
  *             (`[runtime, script, 'sessions', ...]`).
@@ -20,9 +20,9 @@ export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>):
  * Force a forwarded `agents sessions` listing to span the peer's WHOLE index.
  *
  * A remote listing runs in the peer's SSH-login cwd — its home dir — and the
- * default listing is silently cwd-scoped, so `sessions --host box` reads as
+ * default listing is silently cwd-scoped, so `sessions --device box` reads as
  * empty even when the box's index is full (`No sessions found for /home/<user>`).
- * Across SSH a peer's cwd is meaningless, so `--host` defaults to `--all`
+ * Across SSH a peer's cwd is meaningless, so `--device` defaults to `--all`
  * (whole-index) scope. This only drops the *cwd* narrowing — an explicit path
  * query, `--project`, `--since`, or `--agent` filter still narrows on top, and
  * a query that looks like a path takes precedence over `--all` on the remote.