@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/lib/secrets/index.js

@@ -0,0 +1,211 @@
+/**
+ * macOS Keychain integration for secure credential storage.
+ *
+ * Calls a compiled Swift helper (keychain-helper.swift) to store and retrieve
+ * API keys and tokens via the Security framework, with kSecAttrSynchronizable
+ * set so iCloud Keychain syncs them across the user's Macs.
+ */
+import { fileURLToPath } from 'url';
+import { execFileSync, spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const SERVICE_PREFIX = 'agents-cli';
+const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
+/** Parse a bundle YAML value into either a literal string or a typed secret ref. */
+export function parseBundleValue(raw) {
+    if (typeof raw === 'object' && raw !== null && typeof raw.value === 'string') {
+        return { literal: raw.value };
+    }
+    if (typeof raw !== 'string') {
+        throw new Error(`Invalid bundle value (expected string or {value: string}): ${JSON.stringify(raw)}`);
+    }
+    const match = REF_PATTERN.exec(raw);
+    if (!match)
+        return { literal: raw };
+    return { ref: { provider: match[1], value: match[2] } };
+}
+/** Serialize a secret ref back to its `provider:value` string form. */
+export function serializeRef(ref) {
+    return `${ref.provider}:${ref.value}`;
+}
+function assertMacOS() {
+    if (process.platform !== 'darwin') {
+        throw new Error('Keychain-based secrets require macOS. On Linux, use environment variables or .env files instead. Native Linux credential store support is planned.');
+    }
+}
+/** Build the keychain item name for a profile provider token. */
+export function profileKeychainItem(provider) {
+    return `${SERVICE_PREFIX}.${provider}.token`;
+}
+/** Build the keychain item name for a secrets-bundle key. */
+export function secretsKeychainItem(bundle, key) {
+    return `${SERVICE_PREFIX}.secrets.${bundle}.${key}`;
+}
+// Resolve the bundled, signed-and-notarized AgentsKeychain.app shipped
+// alongside the compiled JS. The .app embeds a provisioning profile that
+// grants the application-identifier + keychain-access-groups entitlements
+// macOS requires for kSecAttrSynchronizable writes. Bare CLI binaries
+// (ad-hoc or Developer ID) cannot do this; only an .app with an embedded
+// profile can. So compile-on-first-use is not possible — the binary must
+// be prebuilt by `scripts/build-keychain-helper.sh` and shipped.
+function ensureKeychainHelper() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const binPath = path.join(here, 'AgentsKeychain.app', 'Contents', 'MacOS', 'AgentsKeychain');
+    if (!fs.existsSync(binPath)) {
+        throw new Error(`iCloud Keychain helper missing at ${binPath}. ` +
+            'This npm package was built without the signed helper bundle. ' +
+            'Reinstall agents-cli, or create the bundle without --icloud-sync to use device-local storage.');
+    }
+    return binPath;
+}
+// iCloud Keychain sync is opt-in per bundle. When sync=true we route through
+// the Swift helper (kSecAttrSynchronizable=true). When sync is false/undefined
+// we use /usr/bin/security, which is always present on macOS — so a user who
+// never opts in to iCloud sync never needs Xcode Command Line Tools.
+/** Check if a keychain item exists (macOS only). */
+export function hasKeychainToken(item, sync = false) {
+    assertMacOS();
+    if (sync) {
+        const bin = ensureKeychainHelper();
+        return spawnSync(bin, ['has', item, os.userInfo().username], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).status === 0;
+    }
+    return spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).status === 0;
+}
+/** Retrieve a secret value from the macOS Keychain. Throws if not found. */
+export function getKeychainToken(item, sync = false) {
+    assertMacOS();
+    if (sync) {
+        const bin = ensureKeychainHelper();
+        const result = spawnSync(bin, ['get', item, os.userInfo().username], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        if (result.status === 1)
+            throw new Error(`Keychain item '${item}' not found.`);
+        if (result.status !== 0) {
+            const msg = result.stderr?.toString().trim();
+            throw new Error(msg || `Failed to read keychain item '${item}'.`);
+        }
+        const token = result.stdout?.toString().trim();
+        if (!token)
+            throw new Error(`Keychain item '${item}' exists but is empty.`);
+        return token;
+    }
+    const result = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status === 44)
+        throw new Error(`Keychain item '${item}' not found.`);
+    if (result.status !== 0) {
+        const stderr = result.stderr?.toString() || '';
+        if (/could not be found/i.test(stderr))
+            throw new Error(`Keychain item '${item}' not found.`);
+        throw new Error(`Failed to read keychain item '${item}': ${stderr.trim() || `exit ${result.status}`}`);
+    }
+    const token = result.stdout?.toString().trim();
+    if (!token)
+        throw new Error(`Keychain item '${item}' exists but is empty.`);
+    return token;
+}
+/** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
+export function setKeychainToken(item, value, sync = false) {
+    assertMacOS();
+    if (!value || !value.trim())
+        throw new Error('Secret value is empty.');
+    if (/[\r\n]/.test(value))
+        throw new Error('Secret value contains newlines, which are not supported.');
+    if (sync) {
+        const bin = ensureKeychainHelper();
+        const result = spawnSync(bin, ['set', item, os.userInfo().username], {
+            input: value,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (result.status !== 0) {
+            const msg = result.stderr?.toString().trim();
+            throw new Error(msg || `Failed to write keychain item '${item}'.`);
+        }
+        return;
+    }
+    // The `security -i` interactive form keeps the value out of argv (and `ps`).
+    const user = os.userInfo().username;
+    const cmd = `add-generic-password -a ${quoteForSecurityCli(user)} -s ${quoteForSecurityCli(item)} -w ${quoteForSecurityCli(value)} -U\n`;
+    const result = spawnSync('security', ['-i'], {
+        input: cmd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        throw new Error(`Failed to write keychain item '${item}' (exit ${result.status}).`);
+    }
+}
+/** Delete a keychain item. Returns true if it existed. */
+export function deleteKeychainToken(item, sync = false) {
+    assertMacOS();
+    if (sync) {
+        const bin = ensureKeychainHelper();
+        return spawnSync(bin, ['delete', item, os.userInfo().username], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).status === 0;
+    }
+    return spawnSync('security', ['delete-generic-password', '-a', os.userInfo().username, '-s', item], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).status === 0;
+}
+// Quote a value for `security -i`'s shell-like tokenizer so it stays out of argv.
+function quoteForSecurityCli(s) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+function expandHome(p) {
+    if (p.startsWith('~/') || p === '~') {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+/** Resolve a secret ref to its plaintext value using the appropriate provider. */
+export function resolveRef(ref, opts = {}) {
+    switch (ref.provider) {
+        case 'keychain': {
+            const item = opts.keychainItemFor ? opts.keychainItemFor(ref.value) : ref.value;
+            return getKeychainToken(item, opts.iCloudSync);
+        }
+        case 'env': {
+            const name = ref.value;
+            if (opts.envAllowlist && !opts.envAllowlist.includes(name)) {
+                throw new Error(`env: ref '${name}' not in allowlist.`);
+            }
+            const val = process.env[name];
+            if (val === undefined) {
+                throw new Error(`env: ref '${name}' not set in parent environment.`);
+            }
+            return val;
+        }
+        case 'file': {
+            const target = expandHome(ref.value);
+            if (!fs.existsSync(target)) {
+                throw new Error(`file: ref '${ref.value}' does not exist.`);
+            }
+            return fs.readFileSync(target, 'utf-8').trim();
+        }
+        case 'exec': {
+            if (!opts.allowExec) {
+                throw new Error(`exec: ref '${ref.value}' blocked. Set 'allow_exec: true' in the bundle to enable.`);
+            }
+            // shell: false — the bundle author controls the command; no injection
+            // from secret identifiers. Parse a simple space-separated command.
+            const parts = ref.value.match(/(?:[^\s"]+|"[^"]*")+/g)?.map((p) => p.replace(/^"|"$/g, '')) || [];
+            if (parts.length === 0) {
+                throw new Error(`exec: ref '${ref.value}' is empty.`);
+            }
+            const [cmd, ...args] = parts;
+            try {
+                return execFileSync(cmd, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch (err) {
+                throw new Error(`exec: ref '${ref.value}' failed: ${err.message}`);
+            }
+        }
+    }
+}

package/dist/lib/secrets/profiles.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Thin compatibility shim over the shared secrets library.
+ *
+ * Profile tokens are stored at `agents-cli.<provider>.token`; secrets bundles
+ * live at `agents-cli.secrets.<bundle>.<KEY>`. Both go through the same
+ * keychain primitives in ./index.ts.
+ */
+export { hasKeychainToken, getKeychainToken, setKeychainToken, deleteKeychainToken, } from './index.js';
+/** Map a provider name to its keychain item identifier. */
+export declare function keychainItemName(provider: string): string;

package/dist/lib/secrets/profiles.js

@@ -0,0 +1,13 @@
+/**
+ * Thin compatibility shim over the shared secrets library.
+ *
+ * Profile tokens are stored at `agents-cli.<provider>.token`; secrets bundles
+ * live at `agents-cli.secrets.<bundle>.<KEY>`. Both go through the same
+ * keychain primitives in ./index.ts.
+ */
+export { hasKeychainToken, getKeychainToken, setKeychainToken, deleteKeychainToken, } from './index.js';
+import { profileKeychainItem } from './index.js';
+/** Map a provider name to its keychain item identifier. */
+export function keychainItemName(provider) {
+    return profileKeychainItem(provider);
+}

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

@@ -0,0 +1,43 @@
+export type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
+export type ActiveStatus = 'running' | 'idle' | 'queued' | 'input_required';
+export interface ActiveSession {
+    context: ActiveContext;
+    kind: string;
+    /** Specific host app — 'code', 'cursor', 'codium', 'iterm', 'terminal', 'warp', 'tmux', etc. */
+    host?: string;
+    pid?: number;
+    sessionId?: string;
+    cwd?: string;
+    label?: string;
+    sessionFile?: string;
+    startedAtMs?: number;
+    status: ActiveStatus;
+    teamName?: string;
+    agentId?: string;
+    cloudProvider?: string;
+    cloudTaskId?: string;
+    cloudStatus?: string;
+}
+export interface ActiveQueryOptions {
+    /** Skip the `ps` scan for ad-hoc headless agents. */
+    skipHeadless?: boolean;
+}
+/** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
+export declare function listTeamsActive(): Promise<ActiveSession[]>;
+/** Live editor-terminal agents across every IDE window. */
+export declare function listTerminalsActive(): Promise<ActiveSession[]>;
+/** Cloud tasks still in a non-terminal state. `tasks.db` may not exist; that's fine. */
+export declare function listCloudActive(): ActiveSession[];
+/**
+ * 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 declare function listUnattributedActive(attributed: Set<number>): Promise<ActiveSession[]>;
+/**
+ * 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 declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;

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

@@ -1,5 +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;
-//# sourceMappingURL=artifacts.d.ts.map