@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/session/active.js

@@ -0,0 +1,392 @@
+/**
+ * Active-session detection across every context an agent can run in:
+ *
+ *   - `terminal` — agents launched from VS Code / Cursor / Codium via the
+ *     agents-cli extension. Published to `~/.agents-system/runtime/live-terminals.json`
+ *     with PID + session UUID per entry.
+ *   - `teams`    — agents spawned by `agents teams add`, tracked in
+ *     `~/.agents-system/teams/agents/<id>/meta.json` with a PID the manager polls.
+ *   - `cloud`    — dispatched to Rush / Codex Cloud / Factory, tracked in
+ *     the SQLite cache at `~/.agents-system/cloud/tasks.db`.
+ *   - `headless` — bare `claude` / `codex` / `gemini` / `cursor-agent` /
+ *     `opencode` processes that don't belong to any of the above. Detected
+ *     by `ps` minus the PIDs we've already attributed.
+ *
+ * `running` vs `idle` is a secondary classification within the alive set:
+ * the process is holding its session file, but the file's mtime is older
+ * than ACTIVE_MTIME_WINDOW_MS, so it's probably waiting on the user.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { listActiveTasks } from '../cloud/store.js';
+import { AgentManager } from '../teams/agents.js';
+import { getAgentsDir } from '../state.js';
+const execFileAsync = promisify(execFile);
+const HOME = os.homedir();
+const LIVE_TERMINALS_FILE = path.join(getAgentsDir(), 'runtime', 'live-terminals.json');
+/**
+ * A process is classified `running` if its session file was touched in the
+ * last 2 minutes. Every Claude/Codex tool-call appends an event, so a
+ * healthy session writes several times a minute.
+ */
+const ACTIVE_MTIME_WINDOW_MS = 2 * 60_000;
+/** Executables we recognize as agent CLIs when scanning the process table. */
+const AGENT_CLI_NAMES = {
+    claude: 'claude',
+    codex: 'codex',
+    gemini: 'gemini',
+    'cursor-agent': 'cursor',
+    opencode: 'opencode',
+};
+function isPidAlive(pid) {
+    if (!pid || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === 'EPERM';
+    }
+}
+/** Read the live-terminals registry, dedupe by sessionId, keep only pid-alive entries. */
+function readLiveTerminals() {
+    let raw;
+    try {
+        raw = fs.readFileSync(LIVE_TERMINALS_FILE, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const merged = new Map();
+    for (const slice of Object.values(parsed)) {
+        for (const e of (slice?.entries ?? [])) {
+            if (!e?.sessionId || !isPidAlive(e.pid))
+                continue;
+            merged.set(e.sessionId, e);
+        }
+    }
+    return Array.from(merged.values());
+}
+/** Convert an absolute cwd to the Claude-project folder name (slashes → dashes). */
+function claudeProjectDirName(cwd) {
+    return cwd.replace(/\//g, '-');
+}
+/**
+ * Locate the active Claude session file for a process. If we know the session
+ * UUID (from terminal env or team parent), prefer the exact match. Otherwise
+ * fall back to the most-recent-mtime .jsonl in the project's folder.
+ */
+function findClaudeSessionFile(cwd, sessionId) {
+    const projectDir = path.join(HOME, '.claude', 'projects', claudeProjectDirName(cwd));
+    if (sessionId) {
+        const specific = path.join(projectDir, `${sessionId}.jsonl`);
+        if (fs.existsSync(specific))
+            return specific;
+    }
+    let files;
+    try {
+        files = fs.readdirSync(projectDir).filter(f => f.endsWith('.jsonl'));
+    }
+    catch {
+        return undefined;
+    }
+    let best = null;
+    for (const f of files) {
+        const p = path.join(projectDir, f);
+        try {
+            const m = fs.statSync(p).mtimeMs;
+            if (!best || m > best.mtime)
+                best = { path: p, mtime: m };
+        }
+        catch { /* file vanished between readdir and stat */ }
+    }
+    return best?.path;
+}
+function classifyActivity(sessionFile) {
+    if (!sessionFile)
+        return 'running';
+    try {
+        const mtimeMs = fs.statSync(sessionFile).mtimeMs;
+        return Date.now() - mtimeMs < ACTIVE_MTIME_WINDOW_MS ? 'running' : 'idle';
+    }
+    catch {
+        return 'running';
+    }
+}
+/** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
+export async function listTeamsActive() {
+    const mgr = new AgentManager();
+    const running = await mgr.listRunning();
+    return running.map((a) => {
+        const sessionId = a.parentSessionId ?? a.remoteSessionId ?? undefined;
+        const sessionFile = a.agentType === 'claude' && a.cwd
+            ? findClaudeSessionFile(a.cwd, sessionId ?? undefined)
+            : undefined;
+        return {
+            context: 'teams',
+            kind: a.agentType,
+            pid: a.pid ?? undefined,
+            sessionId,
+            cwd: a.cwd ?? undefined,
+            label: a.name ?? undefined,
+            sessionFile,
+            startedAtMs: a.startedAt.getTime(),
+            status: classifyActivity(sessionFile),
+            teamName: a.taskName,
+            agentId: a.agentId,
+        };
+    });
+}
+/** Live editor-terminal agents across every IDE window. */
+export async function listTerminalsActive() {
+    const entries = readLiveTerminals();
+    if (entries.length === 0)
+        return [];
+    // Walk the shell PIDs through the process table once so we can name the host
+    // (code / cursor / codium) per entry rather than a generic 'terminal'.
+    const procByPid = new Map();
+    for (const r of await readProcessTable())
+        procByPid.set(r.pid, r);
+    return entries.map((t) => {
+        const sessionFile = t.kind === 'claude' && t.cwd
+            ? findClaudeSessionFile(t.cwd, t.sessionId)
+            : undefined;
+        return {
+            context: 'terminal',
+            kind: t.kind,
+            host: detectHost(t.pid, procByPid),
+            pid: t.pid,
+            sessionId: t.sessionId,
+            cwd: t.cwd ?? undefined,
+            label: t.label ?? undefined,
+            sessionFile,
+            startedAtMs: t.startedAtMs,
+            status: classifyActivity(sessionFile),
+        };
+    });
+}
+/** Cloud tasks still in a non-terminal state. `tasks.db` may not exist; that's fine. */
+export function listCloudActive() {
+    let tasks;
+    try {
+        tasks = listActiveTasks();
+    }
+    catch {
+        return [];
+    }
+    return tasks.map((t) => ({
+        context: 'cloud',
+        kind: t.agent || 'cloud',
+        label: t.prompt.length > 60 ? t.prompt.slice(0, 57) + '...' : t.prompt,
+        startedAtMs: Date.parse(t.createdAt) || undefined,
+        status: t.status === 'running'
+            ? 'running'
+            : t.status === 'input_required'
+                ? 'input_required'
+                : 'queued',
+        cloudProvider: t.provider,
+        cloudTaskId: t.id,
+        cloudStatus: t.status,
+    }));
+}
+/**
+ * Ordered ancestor-process matchers. First match wins (most specific to least),
+ * so an IDE renderer is preferred over the terminal-app that launched the IDE,
+ * and a terminal-app is preferred over the multiplexer inside it.
+ */
+const HOST_MATCHERS = [
+    // IDE renderers (Electron helper processes)
+    { host: 'code', tokens: ['Code Helper', 'Code - Insiders Helper'] },
+    { host: 'cursor', tokens: ['Cursor Helper'] },
+    { host: 'codium', tokens: ['VSCodium Helper'] },
+    { host: 'windsurf', tokens: ['Windsurf Helper'] },
+    // Native terminal apps
+    { host: 'iterm', tokens: ['iTerm2', 'iTermServer', 'iTerm'] },
+    { host: 'terminal', tokens: ['Terminal.app', '/Applications/Utilities/Terminal.app'] },
+    { host: 'warp', tokens: ['Warp.app', 'stable_'] },
+    { host: 'alacritty', tokens: ['alacritty', 'Alacritty'] },
+    { host: 'kitty', tokens: ['kitty'] },
+    { host: 'hyper', tokens: ['Hyper.app', 'Hyper Helper'] },
+    { host: 'wezterm', tokens: ['wezterm', 'WezTerm'] },
+    { host: 'ghostty', tokens: ['ghostty', 'Ghostty'] },
+    // Multiplexers (fallback — only if no UI found above them)
+    { host: 'tmux', tokens: ['tmux'] },
+    { host: 'screen', tokens: ['screen'] },
+];
+/**
+ * Snapshot the whole process table in one `ps` call. Includes ppid so we can
+ * walk ancestry chains to attribute child processes to their terminal hosts.
+ * `comm` may be an absolute path for shim-launched agents, so basename before
+ * matching against AGENT_CLI_NAMES.
+ */
+async function readProcessTable() {
+    let out;
+    try {
+        ({ stdout: out } = await execFileAsync('ps', ['-A', '-o', 'pid=,ppid=,comm='], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const line of out.split('\n')) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+        if (!m)
+            continue;
+        const pid = parseInt(m[1], 10);
+        const ppid = parseInt(m[2], 10);
+        if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+            continue;
+        const commRaw = m[3].trim();
+        const kind = AGENT_CLI_NAMES[path.basename(commRaw)];
+        rows.push({ pid, ppid, comm: commRaw, kind });
+    }
+    return rows;
+}
+/**
+ * True when any ancestor in pid's parent chain is a known attributed PID.
+ * VS Code / Cursor terminals store the *shell* PID in live-terminals.json,
+ * while `ps` reports the *child* claude PID, so a direct set lookup misses.
+ */
+function hasAttributedAncestor(pid, ppidMap, attributed) {
+    let cur = ppidMap.get(pid);
+    const seen = new Set();
+    while (cur && cur > 1 && !seen.has(cur)) {
+        if (attributed.has(cur))
+            return true;
+        seen.add(cur);
+        cur = ppidMap.get(cur);
+    }
+    return false;
+}
+/**
+ * Resolve a process's current working directory via `lsof`. The `-a` flag
+ * ANDs the filters; without it macOS treats `-p` and `-d` as a union and
+ * returns the cwd of every process on the system.
+ */
+async function getCwdForPid(pid) {
+    let out;
+    try {
+        const res = await execFileAsync('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+            encoding: 'utf8',
+        });
+        out = res.stdout;
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of out.split('\n')) {
+        if (line.startsWith('n'))
+            return line.slice(1);
+    }
+    return undefined;
+}
+/**
+ * Walk a pid's ancestor chain and return the most specific host app found.
+ * Checks each HOST_MATCHERS entry against every ancestor, returns the first
+ * host whose tokens match — so IDEs beat terminal apps, terminals beat
+ * multiplexers. Returns undefined if nothing is recognised (true headless).
+ */
+function detectHost(pid, procByPid) {
+    const chain = [];
+    let cur = procByPid.get(pid)?.ppid;
+    const seen = new Set();
+    while (cur && cur > 1 && !seen.has(cur)) {
+        const row = procByPid.get(cur);
+        if (!row)
+            break;
+        chain.push(row.comm);
+        seen.add(cur);
+        cur = row.ppid;
+    }
+    for (const { host, tokens } of HOST_MATCHERS) {
+        if (chain.some(c => tokens.some(t => c.includes(t))))
+            return host;
+    }
+    return undefined;
+}
+/** IDE / terminal / multiplexer hosts all count as UI-hosted. Absence = truly headless. */
+const UI_HOSTS = new Set([
+    'code', 'cursor', 'codium', 'windsurf',
+    'iterm', 'terminal', 'warp', 'alacritty', 'kitty', 'hyper', 'wezterm', 'ghostty',
+    'tmux', 'screen',
+]);
+/**
+ * Agent processes not attributed to a team or the runtime registry.
+ * Classified by walking the ppid chain: any recognised UI ancestor (IDE
+ * helper, terminal-app, or multiplexer) means `terminal`; nothing of the
+ * sort means `headless` (daemon, launchd-spawned, orphan).
+ */
+export async function listUnattributedActive(attributed) {
+    const table = await readProcessTable();
+    const procByPid = new Map();
+    const ppidMap = new Map();
+    for (const r of table) {
+        procByPid.set(r.pid, r);
+        ppidMap.set(r.pid, r.ppid);
+    }
+    // Candidate PIDs first — we only shell out to lsof for these, not the whole table.
+    const candidates = [];
+    for (const { pid, kind } of table) {
+        if (!kind)
+            continue;
+        if (attributed.has(pid))
+            continue;
+        if (hasAttributedAncestor(pid, ppidMap, attributed))
+            continue;
+        candidates.push({ pid, kind });
+    }
+    // Run lsof probes in parallel so N spawns take one round-trip, not N.
+    const cwds = await Promise.all(candidates.map(c => getCwdForPid(c.pid)));
+    const out = [];
+    for (let i = 0; i < candidates.length; i++) {
+        const { pid, kind } = candidates[i];
+        const cwd = cwds[i];
+        const sessionFile = kind === 'claude' && cwd ? findClaudeSessionFile(cwd) : undefined;
+        const host = detectHost(pid, procByPid);
+        const context = host && UI_HOSTS.has(host) ? 'terminal' : 'headless';
+        out.push({
+            context,
+            kind,
+            host,
+            pid,
+            cwd,
+            sessionFile,
+            status: classifyActivity(sessionFile),
+        });
+    }
+    return out;
+}
+/**
+ * Union of all four sources. Teams and terminals spawn actual CLI processes
+ * that also show up in `ps`, so headless attribution runs last with the
+ * already-attributed PIDs removed.
+ */
+export async function getActiveSessions(opts = {}) {
+    const [teams, terminals, cloud] = await Promise.all([
+        listTeamsActive().catch(() => []),
+        listTerminalsActive().catch(() => []),
+        Promise.resolve(listCloudActive()),
+    ]);
+    const knownPids = new Set();
+    for (const s of teams)
+        if (s.pid)
+            knownPids.add(s.pid);
+    for (const s of terminals)
+        if (s.pid)
+            knownPids.add(s.pid);
+    const unattributed = opts.skipHeadless ? [] : await listUnattributedActive(knownPids);
+    return [...teams, ...terminals, ...cloud, ...unattributed];
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Session artifact discovery and resolution.
+ *
+ * Scans parsed session events for file-write tool calls (Write, Edit, etc.)
+ * and returns metadata about each artifact: path, authoring tool, existence
+ * on disk, and file size. Used by the artifacts subcommand and session detail views.
+ */
+import type { SessionMeta, SessionArtifact } from './types.js';
+/** Parse a session and return metadata for every file written or edited during it. */
+export declare function discoverArtifacts(meta: SessionMeta): SessionArtifact[];
+/** Refuse to load artifact files larger than this. Returns '' silently above the cap. */
+export declare const ARTIFACT_MAX_BYTES = 50000000;
+/** Read the current contents of an artifact file from disk. Rejects symlinks. */
+export declare function readArtifact(artifact: SessionArtifact): string;
+/** Resolve a user-provided name to an artifact by exact path, basename, or path suffix. */
+export declare function resolveArtifact(artifacts: SessionArtifact[], name: string): SessionArtifact | null;

package/dist/lib/session/artifacts.js

@@ -0,0 +1,95 @@
+/**
+ * Session artifact discovery and resolution.
+ *
+ * Scans parsed session events for file-write tool calls (Write, Edit, etc.)
+ * and returns metadata about each artifact: path, authoring tool, existence
+ * on disk, and file size. Used by the artifacts subcommand and session detail views.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseSession } from './parse.js';
+/** Tool names that produce file artifacts (writes, edits, patches). */
+const WRITE_TOOLS = new Set([
+    'Write', 'Edit', 'write_file', 'edit_file', 'create_file', 'replace', 'patch',
+]);
+/** Parse a session and return metadata for every file written or edited during it. */
+export function discoverArtifacts(meta) {
+    let events;
+    try {
+        events = parseSession(meta.filePath, meta.agent);
+    }
+    catch {
+        return [];
+    }
+    // Map path -> last write event (later occurrence wins for dedup)
+    const latestByPath = new Map();
+    for (const event of events) {
+        if (event.type !== 'tool_use')
+            continue;
+        const tool = event.tool || '';
+        if (!WRITE_TOOLS.has(tool))
+            continue;
+        const p = event.path
+            || event.args?.file_path
+            || event.args?.path
+            || event.args?.filePath
+            || '';
+        if (!p)
+            continue;
+        latestByPath.set(p, { tool, timestamp: event.timestamp });
+    }
+    const artifacts = [];
+    for (const [p, { tool, timestamp }] of latestByPath) {
+        let exists = false;
+        let sizeBytes;
+        try {
+            const stat = fs.lstatSync(p);
+            if (stat.isFile()) {
+                exists = true;
+                sizeBytes = stat.size;
+            }
+        }
+        catch {
+            // file gone, inaccessible, or symlink/special file
+        }
+        artifacts.push({
+            path: p,
+            tool,
+            timestamp,
+            exists,
+            sizeBytes: exists ? sizeBytes : undefined,
+            sessionId: meta.id,
+        });
+    }
+    return artifacts;
+}
+/** Refuse to load artifact files larger than this. Returns '' silently above the cap. */
+export const ARTIFACT_MAX_BYTES = 50_000_000;
+/** Read the current contents of an artifact file from disk. Rejects symlinks. */
+export function readArtifact(artifact) {
+    const stat = fs.lstatSync(artifact.path);
+    if (!stat.isFile()) {
+        throw new Error(`Refusing to read non-regular file: ${artifact.path}`);
+    }
+    if (stat.size > ARTIFACT_MAX_BYTES)
+        return '';
+    return fs.readFileSync(artifact.path, 'utf-8');
+}
+/** Resolve a user-provided name to an artifact by exact path, basename, or path suffix. */
+export function resolveArtifact(artifacts, name) {
+    // Exact path match
+    const exact = artifacts.find(a => a.path === name);
+    if (exact)
+        return exact;
+    // Basename match
+    const byBase = artifacts.filter(a => path.basename(a.path) === name);
+    if (byBase.length === 1)
+        return byBase[0];
+    if (byBase.length > 1)
+        return byBase[0];
+    // Path suffix match (e.g. "src/foo.ts")
+    const bySuffix = artifacts.filter(a => a.path.endsWith('/' + name) || a.path === name);
+    if (bySuffix.length >= 1)
+        return bySuffix[0];
+    return null;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Rush Cloud session source.
+ *
+ * Fetches cloud-captured sessions from halo/proxy (api.prix.dev) and caches
+ * them locally so the existing filesystem-based parse pipeline works unchanged.
+ *
+ * Endpoints consumed (implemented in halo/proxy/src/cloud-runs.ts):
+ *   GET /api/v1/cloud-runs                  → list executions
+ *   GET /api/v1/cloud-runs/:id              → get one (used for meta)
+ *   GET /api/v1/cloud-runs/:id/session.jsonl → raw captured jsonl
+ */
+import type { SessionMeta } from './types.js';
+/**
+ * List cloud executions the user has captured sessions for. Includes
+ * completed + needs_review + failed; an empty session_path means capture
+ * never ran, so those are silently dropped.
+ */
+export declare function discoverCloudSessions(options?: {
+    limit?: number;
+}): Promise<SessionMeta[]>;
+/**
+ * Fetch the jsonl for one cloud execution and stash it in the local cache.
+ * Returns the local file path. Re-fetches on every call (cheap — executions
+ * are immutable once complete). Callers may pass an already-known filePath.
+ */
+export declare function ensureCloudSessionCached(executionId: string, destPath?: string): Promise<string>;
+/** True if filePath points into the cloud session cache dir. */
+export declare function isCloudSessionPath(filePath: string): boolean;
+/** Extract execution_id from a cloud cache path. */
+export declare function executionIdFromCloudPath(filePath: string): string | null;

package/dist/lib/session/cloud.js

@@ -0,0 +1,121 @@
+/**
+ * Rush Cloud session source.
+ *
+ * Fetches cloud-captured sessions from halo/proxy (api.prix.dev) and caches
+ * them locally so the existing filesystem-based parse pipeline works unchanged.
+ *
+ * Endpoints consumed (implemented in halo/proxy/src/cloud-runs.ts):
+ *   GET /api/v1/cloud-runs                  → list executions
+ *   GET /api/v1/cloud-runs/:id              → get one (used for meta)
+ *   GET /api/v1/cloud-runs/:id/session.jsonl → raw captured jsonl
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as yaml from 'yaml';
+import { getAgentsDir } from '../state.js';
+const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
+const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
+const CLOUD_CACHE_DIR = path.join(getAgentsDir(), 'cache', 'cloud-runs');
+function readToken() {
+    if (!fs.existsSync(USER_YAML)) {
+        throw new Error('Not logged in to Rush. Run `rush login` first.');
+    }
+    const raw = fs.readFileSync(USER_YAML, 'utf-8');
+    const data = yaml.parse(raw);
+    const token = data?.session?.access_token;
+    if (!token) {
+        throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
+    }
+    return token;
+}
+async function api(method, endpoint, token) {
+    return fetch(`${PROXY_BASE}${endpoint}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}` },
+    });
+}
+/** Coerce the `agent` field on a cloud-run row to a SessionAgentId. */
+function agentToFormat(agent) {
+    if (agent === 'claude')
+        return 'claude';
+    if (agent === 'codex')
+        return 'codex';
+    if (agent === 'rush')
+        return 'rush';
+    return null;
+}
+/**
+ * List cloud executions the user has captured sessions for. Includes
+ * completed + needs_review + failed; an empty session_path means capture
+ * never ran, so those are silently dropped.
+ */
+export async function discoverCloudSessions(options) {
+    const token = readToken();
+    const limit = options?.limit ?? 50;
+    const res = await api('GET', `/api/v1/cloud-runs?limit=${limit}`, token);
+    if (!res.ok) {
+        throw new Error(`cloud-runs list failed (${res.status})`);
+    }
+    const data = (await res.json());
+    const rows = data.executions ?? [];
+    const out = [];
+    for (const row of rows) {
+        const agent = agentToFormat(row.agent);
+        if (!agent)
+            continue;
+        const id = row.execution_id;
+        const timestamp = row.updated_at || row.created_at || new Date().toISOString();
+        const project = row.repo_owner && row.repo_name ? `${row.repo_owner}/${row.repo_name}` : undefined;
+        // filePath doubles as the sink path for the cached jsonl. parseSession
+        // dispatches on detectAgent which recognizes the `session.<format>.jsonl`
+        // suffix — so the local cache file name must preserve it.
+        const filePath = path.join(CLOUD_CACHE_DIR, id, `session.${agent}.jsonl`);
+        out.push({
+            id,
+            shortId: id.slice(0, 8),
+            agent,
+            timestamp,
+            project,
+            filePath,
+            topic: row.prompt?.split('\n')[0]?.slice(0, 120),
+            label: `[cloud/${row.status}]${row.branch ? ` ${row.branch}` : ''}`,
+        });
+    }
+    out.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return out;
+}
+/**
+ * Fetch the jsonl for one cloud execution and stash it in the local cache.
+ * Returns the local file path. Re-fetches on every call (cheap — executions
+ * are immutable once complete). Callers may pass an already-known filePath.
+ */
+export async function ensureCloudSessionCached(executionId, destPath) {
+    const token = readToken();
+    const res = await api('GET', `/api/v1/cloud-runs/${encodeURIComponent(executionId)}/session.jsonl`, token);
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`session.jsonl fetch ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const format = (res.headers.get('X-Session-Format') || '').toLowerCase();
+    if (!['claude', 'codex', 'rush'].includes(format)) {
+        throw new Error(`Unknown X-Session-Format on cloud response: "${format}"`);
+    }
+    const finalPath = destPath ?? path.join(CLOUD_CACHE_DIR, executionId, `session.${format}.jsonl`);
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    const body = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(finalPath, body);
+    return finalPath;
+}
+/** True if filePath points into the cloud session cache dir. */
+export function isCloudSessionPath(filePath) {
+    return filePath.startsWith(CLOUD_CACHE_DIR);
+}
+/** Extract execution_id from a cloud cache path. */
+export function executionIdFromCloudPath(filePath) {
+    if (!isCloudSessionPath(filePath))
+        return null;
+    const rel = path.relative(CLOUD_CACHE_DIR, filePath);
+    const parts = rel.split(path.sep);
+    return parts[0] || null;
+}