@phnx-labs/agents-cli 1.22.21 → 1.22.23

package/dist/lib/session/insights.js

@@ -0,0 +1,330 @@
+/**
+ * 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
+ * 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
+ * without a database and cheap to re-run. The expensive part is parsing the transcript,
+ * which is why results are cached per session in `session_insights` and recomputed only
+ * when the file's (mtime, size) changes — the same staleness contract as `scan_ledger`.
+ *
+ * Prior art: Claude Code's own `/insights`, which computes a comparable set from
+ * `~/.claude/projects` alone. Two deliberate differences:
+ *
+ *   - It sees ONE account's directory. This reads every indexed session, across every
+ *     Claude account and every other harness, and reports them apart.
+ *   - It collapses conversation branches before counting. agents-cli is file-per-session
+ *     throughout (`discover.ts` keys on the transcript's basename), so session counts
+ *     here will read slightly higher than `/insights` on the same machine. Reported as
+ *     the raw file count rather than quietly differing.
+ */
+import { computeSummaryStats, shortenModel } from './render.js';
+import { classifyFileChanges, EDIT_TOOLS, WRITE_TOOLS } from './digest.js';
+/** File extension → language label. Mirrors the set `/insights` attributes by. */
+const LANGUAGE_BY_EXT = {
+    '.ts': 'TypeScript', '.tsx': 'TypeScript', '.mts': 'TypeScript', '.cts': 'TypeScript',
+    '.js': 'JavaScript', '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript',
+    '.py': 'Python', '.go': 'Go', '.rs': 'Rust', '.rb': 'Ruby', '.java': 'Java',
+    '.kt': 'Kotlin', '.swift': 'Swift', '.c': 'C', '.h': 'C', '.cc': 'C++', '.cpp': 'C++',
+    '.hpp': 'C++', '.cs': 'C#', '.php': 'PHP', '.sh': 'Shell', '.bash': 'Shell',
+    '.zsh': 'Shell', '.fish': 'Shell', '.sql': 'SQL', '.css': 'CSS', '.scss': 'CSS',
+    '.html': 'HTML', '.vue': 'Vue', '.svelte': 'Svelte', '.md': 'Markdown',
+    '.json': 'JSON', '.yaml': 'YAML', '.yml': 'YAML', '.toml': 'TOML',
+};
+/**
+ * Tool-failure categories, matched in order against the result text (lowercased).
+ * Substring rules, not judgement calls — the same shape `/insights` uses, so the
+ * buckets stay comparable. First match wins; anything unmatched is "Other".
+ */
+const ERROR_CATEGORIES = [
+    [['string to replace not found', 'no changes to make'], 'Edit Failed'],
+    [['has been modified since', 'modified since read'], 'File Changed'],
+    [['exceeds maximum', 'too large', 'too long'], 'File Too Large'],
+    [['file not found', 'does not exist', 'no such file'], 'File Not Found'],
+    [['rejected', "doesn't want to proceed", 'user doesn’t want'], 'User Rejected'],
+    [['exit code', 'command failed', 'error:'], 'Command Failed'],
+];
+/**
+ * Gaps longer than this are someone leaving and coming back, not a reply latency.
+ * Counted separately rather than silently dropped.
+ */
+const GAP_CEILING_SECONDS = 3600;
+/** Response-gap buckets, in ascending order. Upper bound is exclusive. */
+const GAP_BUCKETS = [
+    ['<10s', 10], ['10-30s', 30], ['30s-1m', 60], ['1-2m', 120],
+    ['2-5m', 300], ['5-15m', 900], ['15-60m', Infinity],
+];
+function emptyFacets() {
+    return {
+        toolCounts: {}, models: {}, languages: {}, slashCommands: {}, errorCategories: {},
+        interruptions: 0, responseGaps: [], gapsOverCeiling: 0,
+        linesTouchedBefore: 0, linesTouchedAfter: 0, editingToolCalls: 0,
+        filesCreated: 0, filesModified: 0, filesDeleted: 0, gitCommits: 0, gitPushes: 0,
+        shellCommandsSeen: 0,
+        messageHours: new Array(24).fill(0), userTurns: 0, assistantTurns: 0,
+        toolCount: 0, errorCount: 0,
+    };
+}
+function bump(map, key, by = 1) {
+    map[key] = (map[key] ?? 0) + by;
+}
+/**
+ * Lines in a string, 0 for empty. A trailing newline terminates the last line rather
+ * than starting a new one, so `"a\nb\n"` is 2 — `split('\n').length` would say 3 and
+ * over-count every newline-terminated Write by one.
+ */
+function lineCount(text) {
+    if (typeof text !== 'string' || text === '')
+        return 0;
+    const trimmed = text.endsWith('\n') ? text.slice(0, -1) : text;
+    return trimmed.split('\n').length;
+}
+function categorizeError(text) {
+    const lower = text.toLowerCase();
+    for (const [needles, label] of ERROR_CATEGORIES) {
+        if (needles.some((n) => lower.includes(n)))
+            return label;
+    }
+    return 'Other';
+}
+/**
+ * Count invocations of a git subcommand in a shell command line.
+ *
+ * Matches `git commit`, `git -C /repo commit`, and the same again after a `&&`, `||`
+ * or `;`, without trying to parse shell. The subcommand must be its own whitespace-
+ * separated token, so `git-commit` (a different binary) does not count.
+ *
+ * Known limitation, shared with the `/insights` implementation this mirrors: a git
+ * command quoted inside another command (`echo "run git commit later"`) still counts.
+ * Distinguishing that needs a real shell parse, which is not worth it for a rollup.
+ */
+function countGitOp(command, op) {
+    const re = new RegExp(`(?:^|[\\s&|;(])git(?:\\s+[^\\s&|;]+)*?\\s+${op}\\b`, 'g');
+    return (command.match(re) ?? []).length;
+}
+/**
+ * Compute every behavioural facet of one session from its parsed events.
+ *
+ * Pure: no I/O, no clock, no filesystem. `timezoneOffsetMinutes` is injected rather
+ * than read from the environment so the hour histogram is deterministic in tests and
+ * can be re-bucketed for a different display timezone without re-parsing.
+ */
+export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().getTimezoneOffset()) {
+    const f = emptyFacets();
+    const stats = computeSummaryStats(events);
+    f.toolCounts = stats.toolCounts;
+    f.userTurns = stats.userTurns;
+    f.assistantTurns = stats.assistantTurns;
+    f.toolCount = stats.toolCount;
+    f.errorCount = stats.errorCount;
+    const changes = classifyFileChanges(events);
+    for (const c of changes) {
+        if (c.op === 'created')
+            f.filesCreated++;
+        else if (c.op === 'modified')
+            f.filesModified++;
+        else
+            f.filesDeleted++;
+        const dot = c.path.lastIndexOf('.');
+        if (dot > 0) {
+            const lang = LANGUAGE_BY_EXT[c.path.slice(dot).toLowerCase()];
+            if (lang)
+                bump(f.languages, lang);
+        }
+    }
+    // Response gap: assistant goes quiet, user speaks again.
+    //
+    // No lower bound. /insights drops gaps under 2s, which sounds harmless and is not:
+    // measured over 782 real transcripts it censors 28.4% of the sample and inflates the
+    // reported p50 by 63% (143s against a true 88s), because fast replies are common and
+    // dropping them all shifts the median right. A 0-second reply is a real reply.
+    //
+    // The upper bound stays: past an hour the user went away and came back, which is not
+    // a reply latency. It censors 5.5% of gaps, and `gapsOverCeiling` reports how many so
+    // the number is never quietly truncated.
+    let lastAssistantTs = null;
+    for (const e of events) {
+        const ts = new Date(e.timestamp).getTime();
+        const hasTs = !Number.isNaN(ts);
+        switch (e.type) {
+            case 'interrupt':
+                f.interruptions++;
+                break;
+            case 'usage':
+                // shortenModel so the label matches `agents sessions <id>` and `trends`
+                // rather than printing the raw id beside their shortened one.
+                if (e.model)
+                    bump(f.models, shortenModel(e.model));
+                break;
+            case 'error':
+                bump(f.errorCategories, categorizeError(e.content ?? e.output ?? ''));
+                break;
+            case 'message':
+                if (e.role === 'assistant') {
+                    if (hasTs)
+                        lastAssistantTs = ts;
+                    break;
+                }
+                if (e.role !== 'user')
+                    break;
+                if (hasTs) {
+                    // Local-time hour. parse.ts falls back to `new Date()` for a record with no
+                    // timestamp; those are indistinguishable here, but they are rare and would
+                    // only smear the histogram toward the scan time, never invent a session.
+                    const local = new Date(ts - timezoneOffsetMinutes * 60_000);
+                    f.messageHours[local.getUTCHours()]++;
+                    if (lastAssistantTs !== null) {
+                        const gap = (ts - lastAssistantTs) / 1000;
+                        // >= 0 because clock skew between records can produce a negative gap
+                        // (one of -8.662s in a real corpus). Removing the old 2s floor removed
+                        // this guard with it; a negative reply latency is not a data point.
+                        if (gap >= 0 && gap < GAP_CEILING_SECONDS)
+                            f.responseGaps.push(gap);
+                        else if (gap >= GAP_CEILING_SECONDS)
+                            f.gapsOverCeiling++;
+                    }
+                }
+                lastAssistantTs = null;
+                if (e.slashCommand)
+                    bump(f.slashCommands, e.slashCommand);
+                break;
+            case 'tool_use': {
+                if (e._local)
+                    break;
+                if (hasTs)
+                    lastAssistantTs = ts;
+                const args = e.args ?? {};
+                const toolName = e.tool ?? '';
+                // Keyed on the SHARED cross-harness vocabulary, not Claude's literals. Keying
+                // on 'Edit'|'MultiEdit'|'Write' meant codex (whose vocabulary is exec /
+                // exec_command / write_stdin) reported 5,197 tool calls and exactly zero lines
+                // touched, rendered under the same column heading as a real number.
+                if (EDIT_TOOLS.has(toolName)) {
+                    f.linesTouchedBefore += lineCount(args.old_string);
+                    f.linesTouchedAfter += lineCount(args.new_string);
+                    for (const edit of Array.isArray(args.edits) ? args.edits : []) {
+                        f.linesTouchedBefore += lineCount(edit?.old_string);
+                        f.linesTouchedAfter += lineCount(edit?.new_string);
+                    }
+                    f.editingToolCalls++;
+                }
+                else if (WRITE_TOOLS.has(toolName)) {
+                    f.linesTouchedAfter += lineCount(args.content);
+                    f.editingToolCalls++;
+                }
+                if (e.command) {
+                    f.shellCommandsSeen++;
+                    f.gitCommits += countGitOp(e.command, 'commit');
+                    f.gitPushes += countGitOp(e.command, 'push');
+                }
+                break;
+            }
+            default:
+                if (hasTs && e.role === 'assistant')
+                    lastAssistantTs = ts;
+        }
+    }
+    return f;
+}
+/** Percentile of a numeric sample, nearest-rank. Returns 0 for an empty sample. */
+export function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx];
+}
+/** Bucket response gaps for display. Returns every bucket, including empty ones. */
+export function bucketGaps(gaps) {
+    const out = GAP_BUCKETS.map(([bucket]) => ({ bucket, count: 0 }));
+    for (const g of gaps) {
+        for (let i = 0; i < GAP_BUCKETS.length; i++) {
+            if (g < GAP_BUCKETS[i][1]) {
+                out[i].count++;
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Detect concurrent sessions by interval intersection.
+ *
+ * This is the metric that makes the account split legible rather than academic: a
+ * cross-account overlap is `balanced` rotation actively running two orgs' quota at the
+ * same moment. `/insights` has a comparable "multi-clauding" count, but with one
+ * account it can only ever report the same-account case.
+ *
+ * Sweep in start order, keeping only spans that could still intersect, so this is
+ * O(n log n + pairs) rather than O(n^2) over ~3k sessions.
+ */
+export function detectOverlap(spans) {
+    const usable = spans
+        .filter((s) => Number.isFinite(s.startMs) && Number.isFinite(s.endMs) && s.endMs > s.startMs)
+        .sort((a, b) => a.startMs - b.startMs);
+    let overlappingPairs = 0;
+    let crossAccountPairs = 0;
+    const involved = new Set();
+    const active = [];
+    for (const span of usable) {
+        // Drop spans that ended before this one started; they cannot intersect it or
+        // anything after it.
+        for (let i = active.length - 1; i >= 0; i--) {
+            if (active[i].endMs <= span.startMs)
+                active.splice(i, 1);
+        }
+        for (const other of active) {
+            overlappingPairs++;
+            if (other.accountKey !== span.accountKey)
+                crossAccountPairs++;
+            involved.add(other.id);
+            involved.add(span.id);
+        }
+        active.push(span);
+    }
+    return { overlappingPairs, crossAccountPairs, sessionsInvolved: involved.size };
+}
+/** Merge a session's facets into a running total. */
+export function mergeFacets(into, add) {
+    for (const [k, v] of Object.entries(add.toolCounts))
+        bump(into.toolCounts, k, v);
+    for (const [k, v] of Object.entries(add.models))
+        bump(into.models, k, v);
+    for (const [k, v] of Object.entries(add.languages))
+        bump(into.languages, k, v);
+    for (const [k, v] of Object.entries(add.slashCommands))
+        bump(into.slashCommands, k, v);
+    for (const [k, v] of Object.entries(add.errorCategories))
+        bump(into.errorCategories, k, v);
+    into.interruptions += add.interruptions;
+    into.responseGaps.push(...add.responseGaps);
+    into.gapsOverCeiling += add.gapsOverCeiling;
+    into.linesTouchedBefore += add.linesTouchedBefore;
+    into.linesTouchedAfter += add.linesTouchedAfter;
+    into.editingToolCalls += add.editingToolCalls;
+    into.filesCreated += add.filesCreated;
+    into.filesModified += add.filesModified;
+    into.filesDeleted += add.filesDeleted;
+    into.gitCommits += add.gitCommits;
+    into.gitPushes += add.gitPushes;
+    into.shellCommandsSeen += add.shellCommandsSeen;
+    into.userTurns += add.userTurns;
+    into.assistantTurns += add.assistantTurns;
+    into.toolCount += add.toolCount;
+    into.errorCount += add.errorCount;
+    for (let i = 0; i < 24; i++)
+        into.messageHours[i] += add.messageHours[i];
+}
+/** A fresh zeroed accumulator, for callers folding many sessions together. */
+export function newFacetAccumulator() {
+    return emptyFacets();
+}
+/** Top-N entries of a count map, highest first, ties broken by name for determinism. */
+export function topEntries(counts, limit) {
+    return Object.entries(counts)
+        .map(([name, count]) => ({ name, count }))
+        .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+        .slice(0, limit);
+}

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

@@ -34,6 +34,23 @@ export declare function safeReadSessionFile(filePath: string, maxBytes?: number)
 export interface ParseSessionOptions {
     /** Keep normalized tool results compact by default; renderers can request full output. */
     maxToolOutputChars?: number;
+    /**
+     * Emit an `interrupt` event where the transcript records `[Request interrupted`.
+     *
+     * OFF by default, deliberately. That marker is not a user message, and the default
+     * event array is a versioned consumer contract: `agents sessions <id> --json`
+     * serializes it verbatim (see render.ts, issue #743), `computeSummaryStats` folds
+     * every event's timestamp into the session duration, and the live-state reader and
+     * tail renderer inspect fixed-size windows of the last N events. Emitting it
+     * unconditionally changed all four — a measured 12x duration swing on one real
+     * transcript, a new object in a published payload, and an eviction from the
+     * 12-event rate-limit window whose trigger shape (a trailing interrupt) is exactly
+     * a session the user just cancelled.
+     *
+     * `agents insights` opts in: an interruption is a real friction signal, and dropping
+     * it outright is what made it unrecoverable.
+     */
+    includeInterrupts?: boolean;
 }
 export declare function parseSession(filePath: string, agent?: SessionAgentId, opts?: ParseSessionOptions): SessionEvent[];
 /** Infer the agent type from a session file path using known directory conventions. */
@@ -54,14 +71,14 @@ export declare function isCompletedTodoStatus(status: unknown): boolean;
  */
 export declare function summarizeToolUse(tool: string, args?: Record<string, any>): string;
 /** Parse a Claude JSONL session file into normalized events. */
-export declare function parseClaude(filePath: string): SessionEvent[];
+export declare function parseClaude(filePath: string, opts?: ParseSessionOptions): SessionEvent[];
 /**
  * Parse Claude JSONL *content* (already read into a string) into normalized
  * events. Split from `parseClaude` so the tail reader can parse just the last
  * chunk of a file without re-reading the whole thing. Malformed leading lines
  * (a tail that starts mid-line) are skipped by the per-line try/catch below.
  */
-export declare function parseClaudeContent(content: string): SessionEvent[];
+export declare function parseClaudeContent(content: string, opts?: ParseSessionOptions): SessionEvent[];
 /** Parse a Codex JSONL session file into normalized events. */
 export declare function parseCodex(filePath: string): SessionEvent[];
 /**
@@ -116,6 +133,16 @@ export declare function parseGrok(filePath: string): SessionEvent[];
 export declare function parseOpenCode(filePath: string): SessionEvent[];
 /** Parse a Rush JSONL session file into normalized events. */
 export declare function parseRush(filePath: string): SessionEvent[];
+/**
+ * Muse Code session.jsonl → normalized events.
+ *
+ * Muse records an append-only event log. We map:
+ *   - runtime.command_intake.received / turn_submit → user message
+ *   - assistant_message_committed → assistant message
+ *   - model_completed.usage → usage
+ *   - tool-related events when present
+ */
+export declare function parseMuse(filePath: string): SessionEvent[];
 /** Parse a Hermes session JSON file into normalized events. */
 export declare function parseHermes(filePath: string): SessionEvent[];
 /** Parse a Kimi session state.json file by reading its agents/main/wire.jsonl. */

package/dist/lib/session/parse.js

@@ -125,7 +125,7 @@ export function parseSession(filePath, agent, opts = {}) {
     let events;
     switch (detected) {
         case 'claude':
-            events = parseClaude(filePath);
+            events = parseClaude(filePath, opts);
             break;
         case 'codex':
             events = parseCodex(filePath);
@@ -160,6 +160,9 @@ export function parseSession(filePath, agent, opts = {}) {
         case 'cursor':
             events = parseCursor(filePath);
             break;
+        case 'muse':
+            events = parseMuse(filePath);
+            break;
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can
@@ -206,6 +209,13 @@ export function detectAgent(filePath) {
         return 'droid';
     if (filePath.includes('/.cursor/') || filePath.includes('\\.cursor\\'))
         return 'cursor';
+    // Muse sessions: ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
+    if (filePath.includes('/muse/sessions/') ||
+        filePath.includes('\\muse\\sessions\\') ||
+        filePath.includes('/.local/share/muse/') ||
+        filePath.includes('\\.local\\share\\muse\\')) {
+        return 'muse';
+    }
     // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
     const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
     if (cloudMatch)
@@ -311,8 +321,8 @@ function shortenPath(p) {
 // Claude parser
 // ---------------------------------------------------------------------------
 /** Parse a Claude JSONL session file into normalized events. */
-export function parseClaude(filePath) {
-    return parseClaudeContent(safeReadSessionFile(filePath));
+export function parseClaude(filePath, opts = {}) {
+    return parseClaudeContent(safeReadSessionFile(filePath), opts);
 }
 /**
  * Parse Claude JSONL *content* (already read into a string) into normalized
@@ -320,7 +330,7 @@ export function parseClaude(filePath) {
  * chunk of a file without re-reading the whole thing. Malformed leading lines
  * (a tail that starts mid-line) are skipped by the per-line try/catch below.
  */
-export function parseClaudeContent(content) {
+export function parseClaudeContent(content, opts = {}) {
     const lines = content.split('\n').filter(l => l.trim());
     const events = [];
     // Map tool_use id -> {tool, args} for correlating with tool_result
@@ -436,7 +446,15 @@ export function parseClaudeContent(content) {
                 for (const block of contentBlocks) {
                     if (block.type === 'text') {
                         const text = (block.text || '').trim();
-                        if (text && !text.startsWith('[Request interrupted')) {
+                        if (text.startsWith('[Request interrupted')) {
+                            // The harness's marker for a turn the user cut short, not a user
+                            // message. Surfaced only on request — see includeInterrupts for why
+                            // the default stream must stay byte-identical.
+                            if (opts.includeInterrupts) {
+                                events.push({ type: 'interrupt', agent: 'claude', timestamp, content: text });
+                            }
+                        }
+                        else if (text) {
                             events.push({
                                 type: 'message',
                                 agent: 'claude',
@@ -1496,6 +1514,94 @@ export function parseRush(filePath) {
 //     system_prompt, message_count, messages: [{role, content}, ...] }
 // Content may be a string or an array of text parts.
 // ---------------------------------------------------------------------------
+/**
+ * Muse Code session.jsonl → normalized events.
+ *
+ * Muse records an append-only event log. We map:
+ *   - runtime.command_intake.received / turn_submit → user message
+ *   - assistant_message_committed → assistant message
+ *   - model_completed.usage → usage
+ *   - tool-related events when present
+ */
+export function parseMuse(filePath) {
+    const content = safeReadSessionFile(filePath);
+    const lines = content.split('\n').filter((l) => l.trim());
+    const events = [];
+    const museTs = (raw) => {
+        if (typeof raw?.recorded_at === 'number') {
+            const v = raw.recorded_at;
+            const ms = v > 1e14 ? Math.floor(v / 1000) : v;
+            return new Date(ms).toISOString();
+        }
+        return new Date().toISOString();
+    };
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const timestamp = museTs(raw);
+        const payloadType = raw.payload_type;
+        const payload = raw.payload;
+        const event = payload?.event ?? payload;
+        if (payloadType === 'runtime.command_intake.received') {
+            const cmd = payload?.record?.command;
+            if (cmd?.kind === 'turn_submit' && typeof cmd.prompt === 'string' && cmd.prompt.trim()) {
+                events.push({
+                    type: 'message',
+                    agent: 'muse',
+                    timestamp,
+                    role: 'user',
+                    content: cmd.prompt.trim(),
+                });
+            }
+            continue;
+        }
+        if (event?.kind === 'assistant_message_committed' && typeof event.text === 'string') {
+            events.push({
+                type: 'message',
+                agent: 'muse',
+                timestamp,
+                role: 'assistant',
+                content: event.text,
+            });
+            continue;
+        }
+        if (event?.kind === 'model_completed' && event.usage && typeof event.usage === 'object') {
+            const u = event.usage;
+            events.push({
+                type: 'usage',
+                agent: 'muse',
+                timestamp,
+                content: JSON.stringify({
+                    input_tokens: u.input_tokens ?? 0,
+                    output_tokens: u.output_tokens ?? 0,
+                    cached_tokens: u.cached_tokens ?? 0,
+                    reasoning_tokens: u.reasoning_tokens ?? 0,
+                }),
+            });
+            continue;
+        }
+        // Tool call / result shapes when Muse records them under task events
+        if (event?.kind === 'tool_call' || event?.kind === 'tool.called') {
+            const tool = event.tool || event.name || event.tool_name;
+            if (typeof tool === 'string') {
+                events.push({
+                    type: 'tool_use',
+                    agent: 'muse',
+                    timestamp,
+                    tool,
+                    args: typeof event.args === 'object' ? event.args : undefined,
+                    callId: typeof event.call_id === 'string' ? event.call_id : undefined,
+                });
+            }
+        }
+    }
+    return events;
+}
 /** Parse a Hermes session JSON file into normalized events. */
 export function parseHermes(filePath) {
     let session;

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

@@ -73,7 +73,16 @@ export declare function isAutomaticSessionPeer(d: DeviceProfile, self: string):
  * address. `forwardedArgs` are the caller's own sessions args (query + filters,
  * already `--json`) so every peer returns the same slice this machine asked for.
  */
-export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[]): Promise<RemoteListResult>;
+export interface GatherRemoteListOptions {
+    /**
+     * Opt-in early-exit for a globally-unique id lookup (a full UUID): the first
+     * peer to return the matching row resolves the fan-out and cancels the rest.
+     * Omitted for browse/label/prefix sweeps, which must wait for every peer to
+     * know whether the match is unique or conflicting.
+     */
+    isDefinitive?: (session: SessionMeta, machine: string) => boolean;
+}
+export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[], opts?: GatherRemoteListOptions): Promise<RemoteListResult>;
 export interface RemoteToolSearchResult {
     envelopes: Array<{
         machine: string;

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

@@ -191,19 +191,13 @@ export function isAutomaticSessionPeer(d, self) {
         return false;
     return d.platform === 'windows' || d.platform === 'linux' || d.platform === 'macos';
 }
-/**
- * Gather listing sessions from other machines. With an explicit `hosts` list
- * (from `--host`), 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.
- */
-export async function gatherRemoteList(forwardedArgs, hosts) {
+export async function gatherRemoteList(forwardedArgs, hosts, opts) {
     const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
     const result = await gatherRemoteAgentsJson({
         args: forwardedArgs,
         noFanoutEnv: NO_FANOUT_ENV,
         hosts,
+        earlyExit: opts?.isDefinitive ? { isDefinitive: opts.isDefinitive } : undefined,
         parse: (stdout, machine) => parseRemoteListPayload(stdout, machine, safeResolver),
     });
     return {

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

@@ -54,20 +54,74 @@ export declare function classifySshFailure(res: {
     error?: Error | null;
     status: number | null;
 }): SshOutcome;
+/**
+ * How long a successful remote fetch may be served without re-SSHing.
+ * Short on purpose: session listings must stay near-live (RUSH-2062). Match the
+ * active-session snapshot window so surfaces share one freshness model.
+ */
+export declare const REMOTE_CACHE_MAX_AGE_MS = 15000;
 /**
  * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
  * are hashed so distinct queries cache independently; the host stays readable in
  * the filename (sanitised so `user@host` and aliases are filesystem-safe).
  */
 export declare function remoteCachePath(host: string, forwardedArgs: string[]): string;
+/**
+ * Pure freshness check for a remote-sessions cache entry. A reachable host
+ * skips SSH only while this returns true; unreachable fallback ignores age.
+ */
+export declare function isRemoteCacheFresh(mtimeMs: number, nowMs: number, maxAgeMs?: number): boolean;
+export interface RemoteCacheHit {
+    output: string;
+    mtimeMs: number;
+}
+/**
+ * Read a cached remote fetch. When `maxAgeMs` is set, returns null if the
+ * entry is older than the window (cache-first path for reachable hosts).
+ * Omit `maxAgeMs` to accept any age (unreachable fallback).
+ */
+export declare function readRemoteCache(host: string, forwardedArgs: string[], opts?: {
+    maxAgeMs?: number;
+    nowMs?: number;
+}): RemoteCacheHit | null;
 /** Banner shown above replayed cache rows when the peer is offline. */
 export declare function formatStaleBanner(host: string, mtimeMs: number): string;
 /** Message shown when a host is unreachable and there is no cache to fall back to. */
 export declare function formatUnreachable(host: string): string;
+/** Persist a successful fetch for later cache-first / offline replay.
+ * Best-effort: a cache write must never break the live query. Exported for tests. */
+export declare function writeRemoteCache(host: string, forwardedArgs: string[], output: string): void;
+/**
+ * Serve a *fresh* cache entry for a reachable-host skip (no banner — the data
+ * is still within the freshness window). Returns false when missing/stale so
+ * the caller SSHes. RUSH-2062: without this, a reachable host never skipped SSH
+ * even when the cache was just written.
+ */
+export declare function serveWarmRemoteCache(host: string, forwardedArgs: string[], opts?: {
+    maxAgeMs?: number;
+    nowMs?: number;
+}): boolean;
+/** Replay a cached fetch for an unreachable host (any age). Banner goes to
+ * stderr (so a piped stdout stays exactly the cached rows); returns false when
+ * nothing is cached for this exact (host, query). */
+export declare function replayRemoteCache(host: string, forwardedArgs: string[]): boolean;
+export interface RunRemoteSessionsOptions {
+    /** Skip warm cache and SSH every host (force-refresh). */
+    forceRefresh?: boolean;
+    /** Override freshness window for the warm path. */
+    maxAgeMs?: number;
+    /** Clock (tests). */
+    nowMs?: number;
+}
 /**
  * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, writing each remote's output to the terminal. A successful fetch is cached;
- * an unreachable host falls back to that cache (with a stale banner) when present.
+ * SSH, writing each remote's output to the terminal.
+ *
+ * Cache policy (RUSH-2062):
+ * - **Default:** serve a fresh cache hit without SSH; SSH only on miss/stale.
+ * - **`forceRefresh`:** always SSH, then rewrite the cache.
+ * - **Unreachable:** fall back to any cached output (with a stale banner).
+ *
  * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
  * Reads the invocation from `process.argv` (override via `argv` for testing).
  *
@@ -75,4 +129,4 @@ export declare function formatUnreachable(host: string): string;
  * Session output is small and the remote returns quickly, so buffering is
  * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
  */
-export declare function runRemoteSessions(hosts: string[], argv?: string[]): void;
+export declare function runRemoteSessions(hosts: string[], argv?: string[], opts?: RunRemoteSessionsOptions): void;