@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/dist/lib/plugins.js

@@ -11,14 +11,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir } from './state.js';
+import { getPluginsDir, getTrashPluginsDir, getExtraPluginsDir, getProjectPluginsDir, getSystemPluginsDir } from './state.js';
 import { IS_WINDOWS, isWindowsAbsolutePath, homeDir } from './platform/index.js';
 import { assertSafeGitTransport } from './git.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
 import { AGENTS, agentConfigDirName } from './agents.js';
 import { capableAgents, isCapable } from './capabilities.js';
 import { shouldInstallCommandAsSkill, installCommandSkillToVersion } from './command-skills.js';
-import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, } from './plugin-marketplace.js';
+import { copyPluginToMarketplace, syncMarketplaceManifest, registerMarketplace, unregisterMarketplace, addPluginToSettings, removePluginFromSettings, removePluginFromMarketplace, marketplaceIsEmpty, removeEmptyMarketplaceDir, isInstalledInMarketplace, marketplaceRoot, discoverMarketplaces, marketplaceNameFor, MARKETPLACE_NAME, PROJECT_MARKETPLACE_NAME, SYSTEM_MARKETPLACE_NAME, } from './plugin-marketplace.js';
 const PLUGIN_MANIFEST_DIR = '.claude-plugin';
 const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
@@ -186,11 +186,20 @@ export function assertPluginTargetContained(targetRoot, pluginsDir) {
     }
 }
 /**
- * Get a specific plugin by name.
+ * Get a specific plugin by name. On a cross-marketplace name collision the
+ * highest-precedence scope wins (project > extra > user > system) — the same
+ * resolution the sync writer's Map(last-wins) dedupe and collectPluginScopes()
+ * use. discoverPlugins() yields low→high precedence order, so the LAST match is
+ * the winner; returning the first match would resolve to the lowest scope (e.g.
+ * a system plugin over the user's same-named one), which is exactly backwards.
  */
 export function getPlugin(name) {
     const plugins = discoverPlugins();
-    return plugins.find(p => p.name === name) || null;
+    for (let i = plugins.length - 1; i >= 0; i--) {
+        if (plugins[i].name === name)
+            return plugins[i];
+    }
+    return null;
 }
 /**
  * Check if an agent supports a specific plugin.
@@ -382,13 +391,18 @@ export function checkPluginDependencies(manifest) {
 /**
  * Reconstruct a MarketplaceSpec from a marketplace name. The inverse of
  * marketplaceNameFor(): "agents-cli" → user, "agents-project" → project,
- * "agents-<alias>" → extra. The per-version marketplace operations only key off
- * the name (never spec.root), but we resolve the real source root anyway so the
- * spec is honest for any caller that inspects it.
+ * "agents-system" → system, "agents-<alias>" → extra. The per-version
+ * marketplace operations only key off the name (never spec.root), but we
+ * resolve the real source root anyway so the spec is honest for any caller that
+ * inspects it (e.g. descriptionFor, which would otherwise label the system
+ * marketplace as an extra repo named "system").
  */
-function marketplaceSpecForName(name, cwd = process.cwd()) {
+export function marketplaceSpecForName(name, cwd = process.cwd()) {
     if (!name || name === MARKETPLACE_NAME)
         return { kind: 'user' };
+    if (name === SYSTEM_MARKETPLACE_NAME) {
+        return { kind: 'system', root: getSystemPluginsDir() };
+    }
     if (name === PROJECT_MARKETPLACE_NAME) {
         return { kind: 'project', root: getProjectPluginsDir(cwd) ?? '' };
     }
@@ -1096,10 +1110,38 @@ export async function installPlugin(spec) {
         throw new Error(`Installed source has no valid .claude-plugin/plugin.json`);
     }
     const capabilities = inspectPluginCapabilities(targetRoot);
-    // Persist source for future updates
-    fs.writeFileSync(path.join(targetRoot, SOURCE_FILE), JSON.stringify({ source, isGit: !isLocalPath }), 'utf-8');
+    // Persist source for future updates. `version` records the manifest version
+    // at pull time — a baseline that lets the heal path tell "central is an
+    // untouched copy of upstream" (safe to fast-forward) from "the user edited
+    // it" (leave alone) without hashing the whole tree.
+    fs.writeFileSync(path.join(targetRoot, SOURCE_FILE), JSON.stringify({ source, isGit: !isLocalPath, version: manifest.version }), 'utf-8');
     return { name: manifest.name, root: targetRoot, isNew, capabilities };
 }
+/** Read a plugin's `.source` provenance, or null when absent/unreadable. */
+export function readPluginSourceInfo(root) {
+    const f = path.join(root, SOURCE_FILE);
+    if (!fs.existsSync(f))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(f, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the CURRENT upstream manifest version for a local-sourced plugin
+ * (the `.system`/local-path case). Returns null for git sources — reading their
+ * upstream version would need a network fetch, so git plugins are refreshed only
+ * via the explicit `agents plugins update`.
+ */
+export function getUpstreamManifestVersion(info) {
+    if (info.isGit)
+        return null;
+    const resolved = info.source.replace(/^~/, homeDir());
+    const m = loadPluginManifest(resolved);
+    return m?.version ?? null;
+}
 /**
  * Update an installed plugin by re-pulling from its original source.
  * Returns true if the update succeeded.
@@ -1136,11 +1178,14 @@ export async function updatePlugin(name) {
                 : null;
             fs.rmSync(plugin.root, { recursive: true, force: true });
             fs.cpSync(resolvedSource, plugin.root, { recursive: true });
-            fs.writeFileSync(path.join(plugin.root, SOURCE_FILE), JSON.stringify(sourceInfo), 'utf-8');
             if (userConfigBackup !== null) {
                 fs.writeFileSync(userConfigPath, userConfigBackup, 'utf-8');
             }
         }
+        // Re-stamp .source with the freshly pulled manifest version so the baseline
+        // tracks what's now on disk (keeps the heal "unmodified?" check honest).
+        const freshVersion = loadPluginManifest(plugin.root)?.version;
+        fs.writeFileSync(path.join(plugin.root, SOURCE_FILE), JSON.stringify({ ...sourceInfo, version: freshVersion }), 'utf-8');
     }
     catch (err) {
         return { success: false, error: err.message };

package/dist/lib/project-launch.js

@@ -47,6 +47,7 @@ import * as path from 'path';
 import { supports } from './capabilities.js';
 import { getEnabledExtraRepos, getExtraPluginsDir, getPluginsDir, getProjectAgentsDir, getProjectPluginsDir, getSystemPluginsDir, } from './state.js';
 import { getVersionHomePath } from './versions.js';
+import { toPortableKey } from './platform/index.js';
 import { transformSubagentForClaude } from './subagents.js';
 import { compileRulesForProject } from './rules/compile.js';
 import { discoverPluginsInDir, hasPluginExecSurfaces, inspectPluginCapabilities } from './plugins.js';
@@ -88,15 +89,17 @@ export function runLaunchSync(opts) {
 }
 /**
  * Path of the shim's skip-fast sentinel for this (agent, version, cwd) tuple.
- * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation):
- *   slug = PWD with `/` → `_` and ` ` → `_`
+ * Must match the SHIM-SIDE format in src/lib/shims.ts (PROJECT_SLUG derivation),
+ * which is the canonical `toPortableKey` mapping: drop the Windows drive colon
+ * and fold `\`, `/`, and ` ` → `_`. On POSIX this is byte-identical to the old
+ * `/` and ` ` → `_` slug; on Windows it yields a legal filename (no `C:\`).
  *
  * Cache leak note: this dir accumulates one zero-byte file per
  * (agent, version, project) tuple ever launched. Disk impact is negligible
  * (inodes only). A periodic GC belongs in `agents prune` — follow-up.
  */
 function launchSentinelPath(agent, version, cwd) {
-    const slug = cwd.replace(/\//g, '_').replace(/ /g, '_');
+    const slug = toPortableKey(cwd);
     // Prefer $HOME (respects test overrides + matches bash's $HOME expansion in
     // the shim), fall back to os.homedir() so the lookup never resolves to '/'
     // if HOME is somehow unset.

package/dist/lib/sandbox.js

@@ -11,6 +11,7 @@ import * as path from 'path';
 import * as os from 'os';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getRoutinesDir, getUserAgentsDir } from './state.js';
+import { createLink } from './platform/index.js';
 function resolveRealHome() {
     const home = os.homedir();
     try {
@@ -126,9 +127,11 @@ export function symlinkAllowedDirs(overlayHome, dirs) {
         fs.mkdirSync(parentDir, { recursive: true });
         if (!fs.existsSync(symlinkTarget)) {
             try {
-                fs.symlinkSync(realPath, symlinkTarget);
+                // createLink uses a junction for directories on Windows (no elevation),
+                // a plain symlink on POSIX — allowed dirs are directories.
+                createLink(realPath, symlinkTarget);
             }
-            catch { /* symlink already exists */ }
+            catch { /* link already exists or refused */ }
         }
     }
 }

package/dist/lib/self-update.js

@@ -16,6 +16,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
 import { compareVersions } from './versions.js';
+import { needsWindowsShell } from './platform/index.js';
 export const NPM_PACKAGE_NAME = '@phnx-labs/agents-cli';
 /**
  * The directory bun installs global packages into:
@@ -145,7 +146,10 @@ export async function installPackageIntoPrefix(spec, prefix) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
-    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts']);
+    // On Windows `npm` is `npm.cmd`; execFile cannot run it without a shell (ENOENT).
+    await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts'], {
+        shell: needsWindowsShell('npm'),
+    });
 }
 /**
  * Install `spec` into bun's global store with `bun add -g`. bun writes to
@@ -159,7 +163,8 @@ export async function installPackageWithBun(spec) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
-    await execFileAsync('bun', ['add', '-g', spec]);
+    // On Windows `bun` resolves to `bun.exe`/`bun.cmd`; force shell for the .cmd case.
+    await execFileAsync('bun', ['add', '-g', spec], { shell: needsWindowsShell('bun') });
 }
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
 export function readInstalledVersion(packageRoot) {

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

@@ -45,6 +45,10 @@ export interface QueryOptions {
     /** Match any session whose cwd equals this or is a descendant of it. */
     cwdPrefix?: string;
     project?: string;
+    /** Match the full session id or short id, case-insensitively (exact). */
+    idExact?: string;
+    /** Match sessions whose id or short id begins with this (case-insensitive prefix). */
+    idPrefix?: string;
     sinceMs?: number;
     untilMs?: number;
     limit?: number;
@@ -118,6 +122,16 @@ export declare function upsertSessionsBatch(entries: Array<{
  * Leaves FTS5 content/topic/project untouched — cheap to call every run.
  */
 export declare function syncLabels(labelMap: Map<string, string | null>): number;
+/**
+ * Sync topics (session titles) for a set of sessions, keyed by id. For agents
+ * whose human-readable title lives in a side index that updates independently
+ * of the transcript (Codex `session_index.jsonl`), the per-file scan can't see
+ * a title that lands later. This applies those titles by id, updating both
+ * `sessions.topic` and the FTS5 topic column. Only ever sets a non-empty title
+ * and only when it differs from the stored value — cheap to call every run.
+ * Returns the number of rows updated.
+ */
+export declare function syncTopics(topicMap: Map<string, string>): number;
 /** Query sessions from the database, applying filters and ordering by timestamp descending. */
 export declare function querySessions(options?: QueryOptions): SessionMeta[];
 /** Count sessions matching the given filter options. */
@@ -160,6 +174,15 @@ export declare function getAllFilePaths(): Set<string>;
 export declare function getSessionsByFilePaths(paths: string[]): Map<string, SessionMeta>;
 /** Look up a single session by its unique ID. */
 export declare function getSessionById(id: string): SessionMeta | null;
+/**
+ * Resolve a full-or-partial session id against the index, exact-first then
+ * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
+ * SQLite table instead of a pre-loaded array. Matches both the full id and the
+ * short id. An exact hit short-circuits so a complete id never also drags in its
+ * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
+ * ambiguous prefix disambiguates against the caller's context.
+ */
+export declare function findSessionsById(idQuery: string, scope?: Pick<QueryOptions, 'agent' | 'version' | 'cwd' | 'project'>): SessionMeta[];
 /** A single full-text search result with ranking score. */
 export interface FtsHit {
     sessionId: string;

package/dist/lib/session/db.js

@@ -65,6 +65,7 @@ CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
 CREATE INDEX IF NOT EXISTS idx_sessions_agent ON sessions(agent);
 CREATE INDEX IF NOT EXISTS idx_sessions_file_path ON sessions(file_path);
+CREATE INDEX IF NOT EXISTS idx_sessions_short_id ON sessions(short_id);
 
 CREATE VIRTUAL TABLE IF NOT EXISTS session_text USING fts5(
   session_id UNINDEXED,
@@ -558,6 +559,48 @@ export function syncLabels(labelMap) {
     txn(updates);
     return updates.length;
 }
+/**
+ * Sync topics (session titles) for a set of sessions, keyed by id. For agents
+ * whose human-readable title lives in a side index that updates independently
+ * of the transcript (Codex `session_index.jsonl`), the per-file scan can't see
+ * a title that lands later. This applies those titles by id, updating both
+ * `sessions.topic` and the FTS5 topic column. Only ever sets a non-empty title
+ * and only when it differs from the stored value — cheap to call every run.
+ * Returns the number of rows updated.
+ */
+export function syncTopics(topicMap) {
+    if (topicMap.size === 0)
+        return 0;
+    const db = getDB();
+    const ids = [...topicMap.keys()];
+    const CHUNK = 500;
+    const updates = [];
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db
+            .prepare(`SELECT id, topic FROM sessions WHERE id IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            const live = topicMap.get(row.id) ?? '';
+            if (live && live !== (row.topic ?? '')) {
+                updates.push({ id: row.id, topic: live });
+            }
+        }
+    }
+    if (updates.length === 0)
+        return 0;
+    const updSessions = db.prepare(`UPDATE sessions SET topic = ? WHERE id = ?`);
+    const updFts = db.prepare(`UPDATE session_text SET topic = ? WHERE session_id = ?`);
+    const txn = db.transaction((items) => {
+        for (const { id, topic } of items) {
+            updSessions.run(topic, id);
+            updFts.run(topic, id);
+        }
+    });
+    txn(updates);
+    return updates.length;
+}
 /** Convert a raw database row into a SessionMeta object. */
 function rowToMeta(row) {
     return {
@@ -601,13 +644,28 @@ function buildSessionWhere(options) {
         params.push(options.cwd);
     }
     if (options.cwdPrefix) {
+        // Stored cwd uses the host path separator (normalizeCwd → path.resolve), so
+        // the subdir wildcard must too — a hardcoded '/' never matches a Windows
+        // `C:\a\b` subpath and the listing comes back empty.
         where.push('(cwd = ? OR cwd LIKE ?)');
-        params.push(options.cwdPrefix, options.cwdPrefix + '/%');
+        params.push(options.cwdPrefix, options.cwdPrefix + path.sep + '%');
     }
     if (options.project) {
         where.push('LOWER(IFNULL(project, \'\')) LIKE ?');
         params.push(`%${options.project.toLowerCase()}%`);
     }
+    // id lookup. SQLite's LIKE is case-insensitive for ASCII, so a lowercased
+    // pattern matches mixed-case ids; the `=` exact compare adds COLLATE NOCASE
+    // for the same reason. short_id carries its own index (idx_sessions_short_id);
+    // id is the PRIMARY KEY.
+    if (options.idExact) {
+        where.push('(id = ? COLLATE NOCASE OR short_id = ? COLLATE NOCASE)');
+        params.push(options.idExact, options.idExact);
+    }
+    if (options.idPrefix) {
+        where.push('(id LIKE ? OR short_id LIKE ?)');
+        params.push(`${options.idPrefix}%`, `${options.idPrefix}%`);
+    }
     if (typeof options.sinceMs === 'number') {
         // Compare as strings; ISO 8601 timestamps sort lexicographically.
         where.push('timestamp >= ?');
@@ -739,6 +797,23 @@ export function getSessionById(id) {
     const row = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id);
     return row ? rowToMeta(row) : null;
 }
+/**
+ * Resolve a full-or-partial session id against the index, exact-first then
+ * prefix — the DB-backed equivalent of resolveSessionById() that runs over the
+ * SQLite table instead of a pre-loaded array. Matches both the full id and the
+ * short id. An exact hit short-circuits so a complete id never also drags in its
+ * prefix siblings. `scope` narrows by agent / version / project (cwd) so an
+ * ambiguous prefix disambiguates against the caller's context.
+ */
+export function findSessionsById(idQuery, scope = {}) {
+    const q = idQuery.trim();
+    if (!q)
+        return [];
+    const exact = querySessions({ ...scope, idExact: q });
+    if (exact.length > 0)
+        return exact;
+    return querySessions({ ...scope, idPrefix: q });
+}
 /**
  * Escape a raw user query into a safe FTS5 MATCH expression.
  * Splits on non-word characters, keeps tokens >= 2 chars, and OR-joins

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

@@ -36,6 +36,27 @@ export interface ScanProgress {
     parsed: number;
     total: number;
 }
+/** Lightweight metadata extracted from a Claude JSONL file during incremental scan. */
+interface ClaudeSessionScan {
+    timestamp?: string;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    topic?: string;
+    messageCount: number;
+    tokenCount?: number;
+    /** Total USD cost accumulated from per-(model, direction) token usage. */
+    costUsd?: number;
+    /** Wall-clock duration in ms between the first and last timestamped event. */
+    durationMs?: number;
+    /**
+     * Value of the JSONL `entrypoint` field on the first event that carries it.
+     * 'cli' for real interactive sessions, 'sdk-cli' for team-spawned ones.
+     */
+    entrypoint?: string;
+    /** Concatenated user message text, ready to hand to FTS5. */
+    contentText?: string;
+}
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
  * the last run; everything else is served from the SQLite cache.
@@ -77,7 +98,12 @@ export declare function getAgentSessionDirs(agent: string, subdir: string): stri
  * recent startedAt.
  */
 export declare function buildClaudeLabelMap(): Map<string, string | null>;
+/** Parse the lines of a Codex `session_index.jsonl` into a session id -> title map. */
+export declare function parseCodexThreadNameIndex(raw: string): Map<string, string>;
+/** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
+export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
 /** Read up to maxLines non-empty lines from the beginning of a file. */
 export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
 /** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export declare function parseTimeFilter(input: string): number;
+export {};

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,
@@ -486,8 +486,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 +504,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 +522,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) {
@@ -1240,7 +1292,7 @@ function extractHermesMessageText(content) {
         .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 +1300,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 +1347,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 +1412,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/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

@@ -0,0 +1,61 @@
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s1`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters and a leading `-`, so a target
+ * can never be smuggled in as an ssh argv flag.
+ */
+export declare const SSH_TARGET_RE: RegExp;
+export declare function assertValidSshTarget(host: string): void;
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export declare function shellQuote(s: string): string;
+/**
+ * Strip the `--host`/`-H` 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`.
+ *
+ * @param argv full process argv; the sessions args begin at index 2
+ *             (`[runtime, script, 'sessions', ...]`).
+ */
+export declare function buildForwardedArgs(argv: string[], hosts?: Set<string>): string[];
+/**
+ * Build the single remote command string for `ssh <host> <cmd>`. Forwarded args
+ * are quoted for the inner login shell, then the whole `agents …` invocation is
+ * 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, 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;