@phnx-labs/agents-cli 1.20.27 → 1.20.28

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

@@ -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;

package/dist/lib/session/remote.js

@@ -9,12 +9,25 @@
  * upfront copy, always current, but the peer must be reachable. SSH access is the
  * only auth — if you can `ssh <host>`, you own the box (no identity layer by design).
  *
- * Mirrors the transport already used by `agents secrets export --to-ssh`
+ * Offline degradation (no sync, still fetch-first): every *successful* fetch is
+ * cached to `~/.agents/.cache/remote-sessions/`, keyed by host + the exact query.
+ * When a later run finds the host unreachable, the cache is replayed with a clearly
+ * labelled "showing cached results" banner instead of returning nothing. The cache
+ * is a byproduct of fetches you already made — never a background job, freely
+ * deletable — so the fetch-don't-replicate model holds; this is just graceful
+ * degradation when the peer is asleep.
+ *
+ * Mirrors the transport already used by `agents secrets export --host`
  * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
  * with `bash -lc` so the remote login PATH resolves `agents`.
  */
 import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
 import chalk from 'chalk';
+import { getCacheDir } from '../state.js';
+import { formatRelativeTime } from './relative-time.js';
 /**
  * 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
@@ -83,30 +96,124 @@ const SSH_OPTS = [
     '-o', 'StrictHostKeyChecking=accept-new',
     '-o', 'ConnectTimeout=10',
 ];
+/**
+ * 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 function classifySshFailure(res) {
+    if (res.error)
+        return 'spawn-error';
+    if (res.status === 0)
+        return 'ok';
+    if (res.status === 255)
+        return 'unreachable';
+    return 'query-failed';
+}
+/** Root of the offline-replay cache (`~/.agents/.cache/remote-sessions/`). */
+const REMOTE_CACHE_DIR = join(getCacheDir(), 'remote-sessions');
+/**
+ * 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 function remoteCachePath(host, forwardedArgs) {
+    const hash = createHash('sha256').update(forwardedArgs.join('\u0000')).digest('hex').slice(0, 16);
+    const safeHost = host.replace(/[^a-zA-Z0-9._@-]/g, '_');
+    return join(REMOTE_CACHE_DIR, `${safeHost}__${hash}.txt`);
+}
+/** Banner shown above replayed cache rows when the peer is offline. */
+export function formatStaleBanner(host, mtimeMs) {
+    const ago = formatRelativeTime(new Date(mtimeMs).toISOString());
+    return chalk.yellow(`${host}: offline — showing cached results from ${ago}`);
+}
+/** Message shown when a host is unreachable and there is no cache to fall back to. */
+export function formatUnreachable(host) {
+    return chalk.red(`${host}: unreachable over SSH (asleep, offline, or host key changed?) — ConnectTimeout 10s`);
+}
+/** Persist a successful fetch for later offline replay. Best-effort: a cache
+ * write must never break the live query. */
+function writeRemoteCache(host, forwardedArgs, output) {
+    try {
+        mkdirSync(REMOTE_CACHE_DIR, { recursive: true });
+        writeFileSync(remoteCachePath(host, forwardedArgs), output);
+    }
+    catch {
+        // ignore — caching is an optimisation, not a guarantee
+    }
+}
+/** Replay a cached fetch for an unreachable host. Banner goes to stderr (so a
+ * piped stdout stays exactly the cached rows); returns false when nothing is
+ * cached for this exact (host, query). */
+function replayRemoteCache(host, forwardedArgs) {
+    try {
+        const p = remoteCachePath(host, forwardedArgs);
+        if (!existsSync(p))
+            return false;
+        process.stderr.write(formatStaleBanner(host, statSync(p).mtimeMs) + '\n');
+        process.stdout.write(readFileSync(p, 'utf8'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 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 function runRemoteSessions(hosts, argv = process.argv) {
     for (const host of hosts)
         assertValidSshTarget(host); // fail fast on any bad target
-    const remoteCmd = buildRemoteCommand(buildForwardedArgs(argv, new Set(hosts)));
+    const forwarded = buildForwardedArgs(argv, new Set(hosts));
+    const remoteCmd = buildRemoteCommand(forwarded);
     const multi = hosts.length > 1;
     let failures = 0;
     for (const host of hosts) {
         if (multi)
             process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
-        const res = spawnSync('ssh', [...SSH_OPTS, host, remoteCmd], { stdio: 'inherit' });
-        if (res.error) {
-            failures++;
-            console.error(chalk.red(`${host}: ${res.error.message}`));
-            continue;
-        }
-        if (res.status !== 0) {
-            failures++;
-            console.error(chalk.red(`${host}: remote query failed (exit ${res.status ?? 'signal'}).`));
+        const res = spawnSync('ssh', [...SSH_OPTS, host, remoteCmd], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        switch (classifySshFailure(res)) {
+            case 'ok':
+                process.stdout.write(res.stdout ?? '');
+                if (res.stderr)
+                    process.stderr.write(res.stderr);
+                writeRemoteCache(host, forwarded, res.stdout ?? '');
+                break;
+            case 'unreachable':
+                // Served-from-cache counts as answered (degraded, but with data + a clear
+                // banner), so it does not increment failures. No cache → a real failure.
+                if (!replayRemoteCache(host, forwarded)) {
+                    failures++;
+                    console.error(formatUnreachable(host));
+                }
+                break;
+            case 'spawn-error':
+                failures++;
+                console.error(chalk.red(`${host}: ${res.error?.message ?? 'failed to launch ssh'}`));
+                break;
+            case 'query-failed':
+                // The remote ran but its query exited non-zero — surface its own output
+                // and exit code; never mask a genuine error with stale cache.
+                failures++;
+                if (res.stdout)
+                    process.stdout.write(res.stdout);
+                if (res.stderr)
+                    process.stderr.write(res.stderr);
+                console.error(chalk.red(`${host}: remote query failed (exit ${res.status ?? 'signal'}).`));
+                break;
         }
     }
     if (failures > 0)

package/dist/lib/ssh-exec.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared SSH exec primitive — the single hardened choke point for running a
+ * command on a remote host over the system `ssh`.
+ *
+ * `agents hosts` dispatch and the browser driver both go through here so the
+ * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
+ * target-injection guard live in exactly one place. Target validation is the
+ * canonical definition; `commands/secrets.ts` re-exports it.
+ */
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters so a target can't be
+ * smuggled in as part of a remote command, and `sshExec` additionally rejects a
+ * leading `-` so it can never be parsed 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;
+/** Hardened ssh options applied to every connection. */
+export declare const SSH_OPTS: readonly string[];
+export interface SshExecOptions {
+    /** Piped to the remote command's stdin (never interpolated into the shell). */
+    input?: string;
+    /** Kill the ssh process after this many ms. */
+    timeoutMs?: number;
+    /** Extra ssh flags inserted before the target (e.g. `-tt`). */
+    extraSshArgs?: string[];
+}
+export interface SshExecResult {
+    /** Remote exit status, or null if ssh itself failed / timed out. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/**
+ * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
+ *
+ * `remoteCmd` is passed as a single argv to ssh (the remote login shell parses
+ * it); callers that build it from user input must `shellQuote` the pieces.
+ */
+export declare function sshExec(target: string, remoteCmd: string, opts?: SshExecOptions): SshExecResult;
+/** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
+export declare function sshReachable(target: string, timeoutMs?: number): boolean;

package/dist/lib/ssh-exec.js

@@ -0,0 +1,61 @@
+/**
+ * Shared SSH exec primitive — the single hardened choke point for running a
+ * command on a remote host over the system `ssh`.
+ *
+ * `agents hosts` dispatch and the browser driver both go through here so the
+ * connection hardening (`BatchMode`, `accept-new`, `ConnectTimeout`) and the
+ * target-injection guard live in exactly one place. Target validation is the
+ * canonical definition; `commands/secrets.ts` re-exports it.
+ */
+import { spawnSync } from 'child_process';
+/**
+ * SSH target: a bare ssh-config host alias (e.g. `yosemite-s0`) or `user@host`.
+ * The strict allowlist blocks shell metacharacters so a target can't be
+ * smuggled in as part of a remote command, and `sshExec` additionally rejects a
+ * leading `-` so it can never be parsed as an ssh argv flag.
+ */
+export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
+export function assertValidSshTarget(host) {
+    if (host.startsWith('-') || !SSH_TARGET_RE.test(host)) {
+        throw new Error(`Invalid SSH target ${JSON.stringify(host)}. Expected a host alias or user@host (letters, digits, '.', '_', '-').`);
+    }
+}
+/** POSIX single-quote a string for safe interpolation into a remote shell command. */
+export function shellQuote(s) {
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(s))
+        return s;
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/** Hardened ssh options applied to every connection. */
+export const SSH_OPTS = [
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=10',
+];
+/**
+ * Run `remoteCmd` on `target` over ssh and capture stdout/stderr/exit.
+ *
+ * `remoteCmd` is passed as a single argv to ssh (the remote login shell parses
+ * it); callers that build it from user input must `shellQuote` the pieces.
+ */
+export function sshExec(target, remoteCmd, opts = {}) {
+    assertValidSshTarget(target);
+    const args = [...SSH_OPTS, ...(opts.extraSshArgs ?? []), target, remoteCmd];
+    const res = spawnSync('ssh', args, {
+        input: opts.input,
+        encoding: 'utf-8',
+        timeout: opts.timeoutMs,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const timedOut = !!(res.error && res.error.code === 'ETIMEDOUT');
+    return {
+        code: typeof res.status === 'number' ? res.status : null,
+        stdout: res.stdout ?? '',
+        stderr: res.stderr ?? '',
+        timedOut,
+    };
+}
+/** True if `target` is reachable over ssh (a passwordless `true` succeeds quickly). */
+export function sshReachable(target, timeoutMs = 10000) {
+    return sshExec(target, 'true', { timeoutMs }).code === 0;
+}

package/dist/lib/startup/command-registry.d.ts

@@ -67,6 +67,7 @@ export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
 export declare const loadBrowser: ModuleLoader;
 export declare const loadComputer: ModuleLoader;
+export declare const loadHosts: ModuleLoader;
 export declare const loadPull: ModuleLoader;
 export declare const loadPush: ModuleLoader;
 export declare const loadRepo: ModuleLoader;