@phnx-labs/agents-cli 1.20.27 → 1.20.29

package/dist/lib/session/discover.js

@@ -21,7 +21,7 @@ import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
 import { extractSessionTopic } from './prompt.js';
 import { costOfUsage } from '../pricing/index.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
 // location, ~/.agents/.history/versions/) or the system repo (legacy / npm-shipped,
@@ -34,6 +34,7 @@ const RUSH_SESSIONS_DIR = path.join(HOME, '.rush', 'sessions');
 const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
 /** How long OpenClaw channel/cron snapshots stay valid before we re-shell-out. */
 const OPENCLAW_TTL_MS = 60_000;
+const ACTIVE_APPEND_RESCAN_DEBOUNCE_MS = 5_000;
 let cachedOpenClawWorkspaces = null;
 const cachedAgentVersions = new Map();
 /**
@@ -63,6 +64,7 @@ export async function discoverSessions(options) {
                     case 'rush': return scanRushIncremental(onProgress);
                     case 'hermes': return scanHermesIncremental(onProgress);
                     case 'kimi': return scanKimiIncremental(onProgress);
+                    case 'droid': return scanDroidIncremental(onProgress);
                 }
             }));
         }
@@ -164,10 +166,16 @@ export function searchContentIndex(sessions, query) {
 /**
  * For a list of files, stat each, compare to the DB ledger, and return only
  * the ones that need rescanning. One bulk DB query for the whole list.
+ *
+ * Actively running agents append to their JSONL every few seconds. Without a
+ * small debounce, repeated `agents sessions` invocations stream-parse the same
+ * growing transcript over and over. The cached row is good enough for a few
+ * seconds; once writes settle or the debounce expires, the file is parsed once.
  */
 function filterChangedFiles(filePaths) {
     const ledger = getScanStampsForPaths(filePaths);
     const out = [];
+    const now = Date.now();
     for (const filePath of filePaths) {
         const stat = safeStatSync(filePath);
         if (!stat)
@@ -180,10 +188,22 @@ function filterChangedFiles(filePaths) {
         if (prev && prev.fileMtimeMs === scan.fileMtimeMs && prev.fileSize === scan.fileSize) {
             continue;
         }
+        if (prev && shouldDeferRecentAppend(prev, scan, now)) {
+            continue;
+        }
         out.push({ filePath, scan });
     }
     return out;
 }
+export function shouldDeferRecentAppend(prev, current, nowMs, debounceMs = ACTIVE_APPEND_RESCAN_DEBOUNCE_MS) {
+    if (prev.scannedAt === undefined)
+        return false;
+    if (current.fileSize <= prev.fileSize)
+        return false;
+    if (current.fileMtimeMs < prev.fileMtimeMs)
+        return false;
+    return nowMs - prev.scannedAt < debounceMs;
+}
 // ---------------------------------------------------------------------------
 // Multi-version directory scanning
 // ---------------------------------------------------------------------------
@@ -486,8 +506,14 @@ async function scanCodexIncremental(onProgress) {
         }
     }
     const changed = filterChangedFiles(filePaths);
-    if (changed.length === 0)
+    // Codex keeps human-readable titles (`thread_name`) in `session_index.jsonl`,
+    // which updates independently of the rollout files — apply them by id on every
+    // scan so a title that lands after a session was first indexed still surfaces.
+    const titles = readCodexThreadNames();
+    if (changed.length === 0) {
+        syncTopics(titles);
         return;
+    }
     onProgress?.({ agent: 'codex', parsed: 0, total: changed.length });
     const entries = [];
     const touched = [];
@@ -498,6 +524,10 @@ async function scanCodexIncremental(onProgress) {
             const result = await readCodexMeta(filePath, account, currentVersion);
             if (result && !seen.has(result.meta.id)) {
                 seen.add(result.meta.id);
+                // Prefer the Codex-generated title over the first-prompt fallback.
+                const title = titles.get(result.meta.id);
+                if (title)
+                    result.meta.topic = title;
                 entries.push({ meta: result.meta, content: result.content, scan });
             }
             else {
@@ -512,6 +542,48 @@ async function scanCodexIncremental(onProgress) {
     }
     upsertSessionsBatch(entries);
     recordScans(touched);
+    // Catch sessions whose rollout file was unchanged but gained a title since the
+    // last scan (the index changed, the transcript did not).
+    syncTopics(titles);
+}
+/** Parse the lines of a Codex `session_index.jsonl` into a session id -> title map. */
+export function parseCodexThreadNameIndex(raw) {
+    const titles = new Map();
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            const id = typeof entry.id === 'string' ? entry.id : '';
+            const name = typeof entry.thread_name === 'string' ? entry.thread_name.trim() : '';
+            if (id && name)
+                titles.set(id, name);
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return titles;
+}
+/**
+ * Read Codex session titles across every Codex home (live + versioned). The
+ * `session_index.jsonl` file sits beside each `sessions/` rollout tree.
+ */
+function readCodexThreadNames() {
+    const titles = new Map();
+    for (const sessionsDir of getAgentSessionDirs('codex', 'sessions')) {
+        const indexPath = path.join(path.dirname(sessionsDir), 'session_index.jsonl');
+        let raw;
+        try {
+            raw = fs.readFileSync(indexPath, 'utf-8');
+        }
+        catch {
+            continue; // no index in this home
+        }
+        for (const [id, name] of parseCodexThreadNameIndex(raw))
+            titles.set(id, name);
+    }
+    return titles;
 }
 /** Stream-parse a single Codex JSONL file to extract session metadata. */
 async function readCodexMeta(filePath, account, currentVersion) {
@@ -1239,8 +1311,216 @@ function extractHermesMessageText(content) {
         .join('\n')
         .trim();
 }
+/**
+ * Incrementally re-scan changed Droid (Factory) session files and upsert into
+ * the DB. Droid writes one `<uuid>.jsonl` transcript plus a sibling
+ * `<uuid>.settings.json` (model + token usage) under
+ * `~/.factory/sessions/<encoded-cwd>/`.
+ */
+async function scanDroidIncremental(onProgress) {
+    const currentVersion = await getCurrentAgentVersion('droid');
+    const filePaths = [];
+    for (const sessionsDir of getAgentSessionDirs('droid', 'sessions')) {
+        // High limit: we only stat files here, parsing is gated by ledger match.
+        for (const fp of walkForFiles(sessionsDir, '.jsonl', 100_000)) {
+            filePaths.push(fp);
+        }
+    }
+    const changed = filterChangedFiles(filePaths);
+    if (changed.length === 0)
+        return;
+    onProgress?.({ agent: 'droid', parsed: 0, total: changed.length });
+    const entries = [];
+    const touched = [];
+    const seen = new Set();
+    let parsed = 0;
+    for (const { filePath, scan } of changed) {
+        try {
+            const result = await readDroidMeta(filePath, currentVersion);
+            if (result && !seen.has(result.meta.id)) {
+                seen.add(result.meta.id);
+                entries.push({ meta: result.meta, content: result.content, scan });
+            }
+            else {
+                touched.push({ filePath, scan });
+            }
+        }
+        catch {
+            touched.push({ filePath, scan });
+        }
+        parsed++;
+        onProgress?.({ agent: 'droid', parsed, total: changed.length });
+    }
+    upsertSessionsBatch(entries);
+    recordScans(touched);
+}
+/** Stream-parse a single Droid JSONL file (+ sibling settings) into session metadata. */
+async function readDroidMeta(filePath, currentVersion) {
+    const scan = await scanDroidSession(filePath);
+    // The filename is the canonical session id; fall back to the session_start id.
+    const sessionId = path.basename(filePath).replace(/\.jsonl$/, '') || scan.sessionId || '';
+    if (!sessionId)
+        return null;
+    // Token usage and cost live only in the sibling `<uuid>.settings.json`.
+    const settings = readDroidSettings(filePath.replace(/\.jsonl$/, '.settings.json'));
+    const model = settings.model || scan.model;
+    const tokenCount = settings.tokenCount;
+    const costUsd = model && settings.usage
+        ? costOfUsage({
+            model,
+            inputTokens: settings.usage.inputTokens,
+            outputTokens: settings.usage.outputTokens,
+            cacheReadTokens: settings.usage.cacheReadTokens,
+            cacheCreationTokens: settings.usage.cacheCreationTokens,
+        })
+        : 0;
+    const stat = safeStatSync(filePath);
+    const cwd = normalizeCwd(scan.cwd || '');
+    const meta = {
+        id: sessionId,
+        shortId: sessionId.slice(0, 8),
+        agent: 'droid',
+        timestamp: scan.timestamp || (stat ? stat.mtime.toISOString() : new Date().toISOString()),
+        project: cwd ? path.basename(cwd) : undefined,
+        cwd,
+        filePath,
+        version: resolveSessionVersion('droid', filePath, undefined, currentVersion),
+        topic: scan.topic,
+        messageCount: scan.messageCount,
+        tokenCount,
+        costUsd: costUsd > 0 ? costUsd : undefined,
+        durationMs: scan.durationMs,
+    };
+    return { meta, content: scan.contentText || '' };
+}
+/** Read model + token usage from a Droid `<uuid>.settings.json` sidecar. */
+function readDroidSettings(settingsPath) {
+    try {
+        const data = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        const model = typeof data.model === 'string' ? data.model : undefined;
+        const u = data.tokenUsage;
+        if (!u || typeof u !== 'object')
+            return { model };
+        const usage = {
+            inputTokens: u.inputTokens,
+            outputTokens: u.outputTokens,
+            cacheReadTokens: u.cacheReadTokens,
+            cacheCreationTokens: u.cacheCreationTokens,
+        };
+        const tokenCount = sumKnownNumbers([
+            u.inputTokens,
+            u.outputTokens,
+            u.cacheCreationTokens,
+            u.cacheReadTokens,
+        ]) ?? undefined;
+        return { model, tokenCount, usage };
+    }
+    catch {
+        return {};
+    }
+}
+/** Stream a Droid JSONL file and extract scan-level metadata (id, cwd, topic, model, duration). */
+async function scanDroidSession(filePath) {
+    const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let sessionId;
+    let timestamp;
+    let cwd;
+    let title;
+    let sessionTitle;
+    let firstUserTopic;
+    let model;
+    let messageCount = 0;
+    let firstTsMs;
+    let lastTsMs;
+    const userTexts = [];
+    try {
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (parsed.type === 'session_start') {
+                sessionId = typeof parsed.id === 'string' ? parsed.id : sessionId;
+                cwd = typeof parsed.cwd === 'string' ? parsed.cwd : cwd;
+                // Droid auto-generates `sessionTitle`; `title` is the raw first prompt.
+                if (typeof parsed.sessionTitle === 'string' && parsed.sessionTitle.trim()) {
+                    sessionTitle = parsed.sessionTitle.trim();
+                }
+                if (typeof parsed.title === 'string' && parsed.title.trim()) {
+                    title = parsed.title.trim();
+                }
+                continue;
+            }
+            if (parsed.type !== 'message')
+                continue;
+            // Track duration across every timestamped message.
+            if (typeof parsed.timestamp === 'string') {
+                const ms = new Date(parsed.timestamp).getTime();
+                if (!Number.isNaN(ms)) {
+                    if (firstTsMs === undefined || ms < firstTsMs)
+                        firstTsMs = ms;
+                    if (lastTsMs === undefined || ms > lastTsMs)
+                        lastTsMs = ms;
+                }
+            }
+            if (!timestamp && typeof parsed.timestamp === 'string')
+                timestamp = parsed.timestamp;
+            const msg = parsed.message || {};
+            if (typeof msg.modelId === 'string')
+                model = msg.modelId;
+            const text = extractDroidMessageText(msg.content);
+            if (!text)
+                continue;
+            messageCount++;
+            if (msg.role === 'user') {
+                userTexts.push(text);
+                if (!firstUserTopic)
+                    firstUserTopic = extractSessionTopic(text);
+            }
+        }
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
+        ? lastTsMs - firstTsMs
+        : undefined;
+    return {
+        sessionId,
+        timestamp,
+        cwd,
+        // Prefer Droid's auto-title, then the raw first-prompt title, then the
+        // derived first-user-message topic.
+        topic: sessionTitle || title || firstUserTopic,
+        model,
+        messageCount,
+        durationMs,
+        contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
+    };
+}
+/** Extract plain text from a Droid message content field (Anthropic-shaped blocks). */
+function extractDroidMessageText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => (typeof part?.text === 'string' && part.type === 'text' ? part.text : ''))
+        // Droid front-loads injected context (date, skills list) as <system-reminder>
+        // text blocks on the first user turn — drop them so topic/content stay clean.
+        .filter((text) => text.trim() && !text.trim().startsWith('<system-reminder>'))
+        .join('\n')
+        .trim();
+}
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
-async function scanClaudeSession(filePath) {
+export async function scanClaudeSession(filePath) {
     const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
     const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
     let timestamp;
@@ -1248,6 +1528,10 @@ async function scanClaudeSession(filePath) {
     let gitBranch;
     let version;
     let topic;
+    // Explicit session titles: `/rename` writes a `custom-title` event; Claude
+    // auto-generates an `ai-title`. Both can repeat across the file — last wins.
+    let customTitle;
+    let aiTitle;
     let entrypoint;
     let messageCount = 0;
     let tokenCount = 0;
@@ -1291,6 +1575,18 @@ async function scanClaudeSession(filePath) {
                 gitBranch = parsed.gitBranch || undefined;
                 version = parsed.version || undefined;
             }
+            if (parsed.type === 'custom-title') {
+                const t = typeof parsed.customTitle === 'string' ? parsed.customTitle.trim() : '';
+                if (t)
+                    customTitle = t;
+                continue;
+            }
+            if (parsed.type === 'ai-title') {
+                const t = typeof parsed.aiTitle === 'string' ? parsed.aiTitle.trim() : '';
+                if (t)
+                    aiTitle = t;
+                continue;
+            }
             if (parsed.type === 'user') {
                 const text = extractClaudeUserText(parsed);
                 if (text) {
@@ -1344,12 +1640,15 @@ async function scanClaudeSession(filePath) {
     const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
         ? lastTsMs - firstTsMs
         : undefined;
+    // Prefer an explicit session title (user `/rename` > Claude auto-title) over
+    // the first-prompt topic.
+    const resolvedTopic = customTitle || aiTitle || topic;
     return {
         timestamp,
         cwd,
         gitBranch,
         version,
-        topic,
+        topic: resolvedTopic,
         entrypoint,
         messageCount,
         tokenCount: sawTokenCount ? tokenCount : undefined,

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

@@ -51,3 +51,10 @@ export declare function parseRush(filePath: string): SessionEvent[];
 export declare function parseHermes(filePath: string): SessionEvent[];
 /** Parse a Kimi session state.json file by reading its agents/main/wire.jsonl. */
 export declare function parseKimi(filePath: string): SessionEvent[];
+/**
+ * Parse a Droid (Factory) JSONL session file into normalized events. Droid
+ * wraps each turn in a `{type:'message', message:{role, content, modelId}}`
+ * envelope; the content blocks are Anthropic-shaped (text/thinking/tool_use/
+ * tool_result), so block handling mirrors the Claude parser.
+ */
+export declare function parseDroid(filePath: string): SessionEvent[];

package/dist/lib/session/parse.js

@@ -109,6 +109,9 @@ export function parseSession(filePath, agent) {
         case 'kimi':
             events = parseKimi(filePath);
             break;
+        case 'droid':
+            events = parseDroid(filePath);
+            break;
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can
@@ -133,6 +136,8 @@ export function detectAgent(filePath) {
         return 'hermes';
     if (filePath.includes('/.kimi-code/') || filePath.includes('\\.kimi-code\\'))
         return 'kimi';
+    if (filePath.includes('/.factory/') || filePath.includes('\\.factory\\'))
+        return 'droid';
     // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
     const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
     if (cloudMatch)
@@ -1124,3 +1129,108 @@ export function parseKimi(filePath) {
     }
     return events;
 }
+// ---------------------------------------------------------------------------
+// Droid (Factory) parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a Droid (Factory) JSONL session file into normalized events. Droid
+ * wraps each turn in a `{type:'message', message:{role, content, modelId}}`
+ * envelope; the content blocks are Anthropic-shaped (text/thinking/tool_use/
+ * tool_result), so block handling mirrors the Claude parser.
+ */
+export function parseDroid(filePath) {
+    const content = safeReadSessionFile(filePath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    // Map tool_use id -> {tool, args} for correlating with tool_result.
+    const toolUseMap = new Map();
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (raw.type !== 'message')
+            continue;
+        const message = raw.message || {};
+        const role = message.role === 'user' ? 'user' : 'assistant';
+        const timestamp = raw.timestamp || new Date().toISOString();
+        const blocks = message.content;
+        // Plain-string content (rare) renders as a single message.
+        if (typeof blocks === 'string') {
+            const text = blocks.trim();
+            if (text)
+                events.push({ type: 'message', agent: 'droid', timestamp, role, content: text });
+            continue;
+        }
+        if (!Array.isArray(blocks))
+            continue;
+        for (const block of blocks) {
+            if (block.type === 'text') {
+                const text = (block.text || '').trim();
+                // Skip injected context blocks (date, skills list) on the first user turn.
+                if (text && !(role === 'user' && text.startsWith('<system-reminder>'))) {
+                    events.push({ type: 'message', agent: 'droid', timestamp, role, content: text });
+                }
+            }
+            else if (block.type === 'thinking') {
+                const thinkingText = (block.thinking || '').trim();
+                if (thinkingText)
+                    events.push({ type: 'thinking', agent: 'droid', timestamp, content: thinkingText });
+            }
+            else if (block.type === 'tool_use') {
+                const toolName = block.name || 'unknown';
+                const toolInput = block.input || {};
+                if (block.id)
+                    toolUseMap.set(block.id, { tool: toolName, args: toolInput });
+                events.push({
+                    type: 'tool_use',
+                    agent: 'droid',
+                    timestamp,
+                    tool: toolName,
+                    args: toolInput,
+                    path: toolInput.file_path || toolInput.path || undefined,
+                    command: toolName === 'Bash' ? toolInput.command : undefined,
+                });
+            }
+            else if (block.type === 'tool_result') {
+                const toolId = block.tool_use_id;
+                const toolInfo = toolId ? toolUseMap.get(toolId) : undefined;
+                const isError = block.is_error === true;
+                let output = '';
+                if (typeof block.content === 'string') {
+                    output = block.content;
+                }
+                else if (Array.isArray(block.content)) {
+                    output = block.content
+                        .filter((c) => c.type === 'text')
+                        .map((c) => c.text || '')
+                        .join('\n');
+                }
+                if (isError) {
+                    events.push({ type: 'error', agent: 'droid', timestamp, tool: toolInfo?.tool, content: output || 'Tool execution failed' });
+                }
+                else {
+                    events.push({
+                        type: 'tool_result',
+                        agent: 'droid',
+                        timestamp,
+                        tool: toolInfo?.tool,
+                        success: true,
+                        output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                    });
+                }
+                if (toolId)
+                    toolUseMap.delete(toolId);
+            }
+            else if (block.type === 'image') {
+                const source = block.source || {};
+                const sizeBytes = source.type === 'base64' ? Math.ceil((source.data?.length || 0) * 0.75) : 0;
+                events.push({ type: 'attachment', agent: 'droid', timestamp, mediaType: source.media_type || 'image/png', sizeBytes });
+            }
+        }
+    }
+    return events;
+}

package/dist/lib/session/relative-time.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Human-readable "time since" formatting for session timestamps. Lives here (not
+ * inline in `sessions.ts`) so both the session list renderer and the remote
+ * offline-cache banner (`remote.ts`) share one formatter — `sessions.ts` imports
+ * `remote.ts`, so a back-import would cycle.
+ */
+export declare function formatRelativeTime(isoTimestamp: string): string;

package/dist/lib/session/relative-time.js

@@ -0,0 +1,28 @@
+/**
+ * Human-readable "time since" formatting for session timestamps. Lives here (not
+ * inline in `sessions.ts`) so both the session list renderer and the remote
+ * offline-cache banner (`remote.ts`) share one formatter — `sessions.ts` imports
+ * `remote.ts`, so a back-import would cycle.
+ */
+export function formatRelativeTime(isoTimestamp) {
+    const now = Date.now();
+    const then = new Date(isoTimestamp).getTime();
+    if (isNaN(then))
+        return isoTimestamp;
+    const diffMs = now - then;
+    const diffMin = Math.floor(diffMs / 60_000);
+    const diffHrs = Math.floor(diffMs / 3_600_000);
+    const diffDays = Math.floor(diffMs / 86_400_000);
+    if (diffMin < 1)
+        return 'just now';
+    if (diffMin < 60)
+        return `${diffMin} min ago`;
+    if (diffHrs < 24)
+        return `${diffHrs} hour${diffHrs === 1 ? '' : 's'} ago`;
+    if (diffDays < 7)
+        return `${diffDays} day${diffDays === 1 ? '' : 's'} ago`;
+    // Older: show date
+    const d = new Date(then);
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    return `${months[d.getMonth()]} ${d.getDate()}`;
+}

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

@@ -24,10 +24,38 @@ export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>):
  * quoted again so it survives `bash -lc <...>`.
  */
 export declare function buildRemoteCommand(forwardedArgs: string[]): string;
+/** The four outcomes of one `ssh <host> agents sessions …` invocation. */
+export type SshOutcome = 'ok' | 'unreachable' | 'query-failed' | 'spawn-error';
+/**
+ * Classify an ssh `spawnSync` result. ssh(1) reserves exit 255 for its own
+ * connection-layer failures (host down, timeout, refused, auth, changed host
+ * key) — distinct from any other non-zero, which is the remote `agents sessions`
+ * exit code forwarded back (the query ran but failed). The two must be handled
+ * differently: 255 may fall back to cache, a forwarded failure must surface.
+ */
+export declare function classifySshFailure(res: {
+    error?: Error | null;
+    status: number | null;
+}): SshOutcome;
+/**
+ * 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;
+/** 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;
 /**
  * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, streaming each remote's output to the terminal. Sets `process.exitCode = 1`
- * if any host fails. Reads the invocation from `process.argv` (override via
- * `argv` for testing).
+ * 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.
+ * 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).
+ *
+ * Output is captured rather than `stdio: 'inherit'`-streamed so it can be cached.
+ * 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;