@phnx-labs/agents-cli 1.14.7 → 1.15.0

package/dist/lib/runner.js

@@ -14,7 +14,7 @@ import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, } from './rout
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
-import { emitStart, maybeRotate } from './events.js';
+import { createTimer, maybeRotate, truncate } from './events.js';
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
@@ -109,11 +109,13 @@ function generateRunId() {
 /** Execute a job synchronously (waits for completion or timeout before resolving). */
 export async function executeJob(config) {
     maybeRotate();
-    const done = emitStart('agent.run.start', {
+    const timer = createTimer('agent.run', {
         agent: config.agent,
         version: config.version,
         jobName: config.name,
         mode: config.mode,
+        prompt: truncate(config.prompt, 200),
+        schedule: config.schedule,
     });
     const resolvedPrompt = resolveJobPrompt(config);
     const cmd = buildJobCommand(config, resolvedPrompt);
@@ -146,6 +148,8 @@ export async function executeJob(config) {
             detached: true,
             env: spawnEnv,
         });
+        // Mark startup time (time from function call to process spawn)
+        timer.mark('startup');
         meta.pid = child.pid || null;
         writeRunMeta(meta);
         let settled = false;
@@ -168,7 +172,7 @@ export async function executeJob(config) {
             meta.status = 'timeout';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
-            done({ status: 'timeout', runId });
+            timer.end({ status: 'timeout', runId });
             const reportPath = extractAndSaveReport(stdoutPath, config.agent, runDir);
             resolve({ meta, reportPath });
         }, timeoutMs);
@@ -185,7 +189,7 @@ export async function executeJob(config) {
             meta.status = code === 0 ? 'completed' : 'failed';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
-            done({ status: meta.status, exitCode: code, runId });
+            timer.end({ status: meta.status, exitCode: code ?? undefined, runId });
             const reportPath = extractAndSaveReport(stdoutPath, config.agent, runDir);
             resolve({ meta, reportPath });
         });
@@ -201,7 +205,7 @@ export async function executeJob(config) {
             meta.status = 'failed';
             meta.completedAt = new Date().toISOString();
             writeRunMeta(meta);
-            done({ status: 'failed', error: err.message, runId });
+            timer.end({ status: 'failed', error: err.message, runId });
             resolve({ meta, reportPath: null });
         });
         child.unref();

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

@@ -1,11 +1,14 @@
 /**
- * macOS Keychain integration for secure credential storage.
+ * Cross-platform secure credential storage.
  *
- * All reads/writes go through a signed Swift helper (keychain-helper.swift)
- * compiled into AgentsKeychain.app. The .app embeds a provisioning profile
- * that grants the application-identifier + keychain-access-groups entitlement
- * macOS requires for kSecAttrSynchronizable writes (iCloud Keychain).
- * For device-local writes the helper is invoked with the `nosync` arg.
+ * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
+ * Windows: Not yet supported.
+ *
+ * The .app embeds a provisioning profile that grants the application-identifier
+ * + keychain-access-groups entitlement macOS requires for kSecAttrSynchronizable
+ * writes (iCloud Keychain). For device-local writes the helper is invoked with
+ * the `nosync` arg.
  */
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
@@ -49,15 +52,15 @@ export interface KeychainBackend {
 }
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
 export declare function setKeychainBackendForTest(b: KeychainBackend | null): KeychainBackend | null;
-/** Check if a keychain item exists (macOS only). */
+/** Check if a keychain/keyring item exists. */
 export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
-/** Retrieve a secret value from the macOS Keychain. Throws if not found. */
+/** Retrieve a secret value from the keychain/keyring. Throws if not found. */
 export declare function getKeychainToken(item: string, sync?: boolean): string;
-/** Store or update a secret value in the macOS Keychain. iCloud-synced when sync=true. */
+/** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
-/** Delete a keychain item. Returns true if it existed. */
+/** Delete a keychain/keyring item. Returns true if it existed. */
 export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
-/** Enumerate keychain item service names whose name starts with the given prefix. */
+/** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(prefix: string): string[];
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {

package/dist/lib/secrets/index.js

@@ -1,17 +1,21 @@
 /**
- * macOS Keychain integration for secure credential storage.
+ * Cross-platform secure credential storage.
  *
- * All reads/writes go through a signed Swift helper (keychain-helper.swift)
- * compiled into AgentsKeychain.app. The .app embeds a provisioning profile
- * that grants the application-identifier + keychain-access-groups entitlement
- * macOS requires for kSecAttrSynchronizable writes (iCloud Keychain).
- * For device-local writes the helper is invoked with the `nosync` arg.
+ * macOS: Uses Keychain via signed Swift helper (AgentsKeychain.app) or `security` CLI.
+ * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
+ * Windows: Not yet supported.
+ *
+ * The .app embeds a provisioning profile that grants the application-identifier
+ * + keychain-access-groups entitlement macOS requires for kSecAttrSynchronizable
+ * writes (iCloud Keychain). For device-local writes the helper is invoked with
+ * the `nosync` arg.
  */
 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';
+import { linuxBackend } from './linux.js';
 const SERVICE_PREFIX = 'agents-cli';
 const REF_PATTERN = /^(keychain|env|file|exec):(.+)$/s;
 /** Parse a bundle value into either a literal string or a typed secret ref. */
@@ -31,11 +35,18 @@ export function parseBundleValue(raw) {
 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.');
+function assertSupportedPlatform() {
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+        throw new Error('Secure credential storage requires macOS or Linux. ' +
+            'On Windows, use environment variables or .env files instead.');
     }
 }
+function isLinux() {
+    return process.platform === 'linux';
+}
+function isMacOS() {
+    return process.platform === 'darwin';
+}
 /** Build the keychain item name for a profile provider token. */
 export function profileKeychainItem(provider) {
     return `${SERVICE_PREFIX}.${provider}.token`;
@@ -73,12 +84,14 @@ export function setKeychainBackendForTest(b) {
 // holds the keychain-access-groups entitlement macOS requires for
 // kSecAttrSynchronizable. Enumeration also goes through the .app because the
 // security CLI doesn't expose listing by service prefix.
-/** Check if a keychain item exists (macOS only). */
+/** Check if a keychain/keyring item exists. */
 export function hasKeychainToken(item, sync = false) {
     if (backend)
         return backend.has(item, sync);
-    assertMacOS();
-    // Try security first (no prompts for local items), fall back to binary for synced items.
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.has(item, sync);
+    // macOS: Try security first (no prompts for local items), fall back to binary for synced items.
     if (spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0)
@@ -89,12 +102,14 @@ export function hasKeychainToken(item, sync = false) {
         stdio: ['ignore', 'pipe', 'pipe'],
     }).status === 0;
 }
-/** Retrieve a secret value from the macOS Keychain. Throws if not found. */
+/** Retrieve a secret value from the keychain/keyring. Throws if not found. */
 export function getKeychainToken(item, sync = false) {
     if (backend)
         return backend.get(item, sync);
-    assertMacOS();
-    // Try security first (no prompts for local items)
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.get(item, sync);
+    // macOS: Try security first (no prompts for local items)
     const secResult = spawnSync('security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -119,17 +134,24 @@ export function getKeychainToken(item, sync = false) {
         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. */
+/** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
 export function setKeychainToken(item, value, sync = false) {
     if (backend) {
         backend.set(item, value, sync);
         return;
     }
-    assertMacOS();
+    assertSupportedPlatform();
     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 (/[\x00=\r\n]/.test(item))
+        throw new Error('Secret item name contains invalid characters.');
+    if (isLinux()) {
+        linuxBackend.set(item, value, sync);
+        return;
+    }
+    // macOS path
     if (sync) {
         const bin = ensureKeychainHelper();
         const result = spawnSync(bin, ['set', item, os.userInfo().username], {
@@ -153,11 +175,14 @@ export function setKeychainToken(item, value, sync = false) {
         throw new Error(`Failed to write keychain item '${item}' (exit ${result.status}).`);
     }
 }
-/** Delete a keychain item. Returns true if it existed. */
+/** Delete a keychain/keyring item. Returns true if it existed. */
 export function deleteKeychainToken(item, sync = false) {
     if (backend)
         return backend.delete(item, sync);
-    assertMacOS();
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.delete(item, sync);
+    // macOS path
     if (sync) {
         const bin = ensureKeychainHelper();
         return spawnSync(bin, ['delete', item, os.userInfo().username], {
@@ -171,11 +196,14 @@ export function deleteKeychainToken(item, sync = false) {
 function quoteForSecurityCli(s) {
     return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
 }
-/** Enumerate keychain item service names whose name starts with the given prefix. */
+/** Enumerate keychain/keyring item names starting with the given prefix. */
 export function listKeychainItems(prefix) {
     if (backend)
         return backend.list(prefix);
-    assertMacOS();
+    assertSupportedPlatform();
+    if (isLinux())
+        return linuxBackend.list(prefix);
+    // macOS path
     const bin = ensureKeychainHelper();
     const result = spawnSync(bin, ['list', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],

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

@@ -0,0 +1,27 @@
+/**
+ * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
+ *
+ * Uses `secret-tool` CLI which is part of libsecret-tools package.
+ * On Ubuntu: apt install libsecret-tools
+ *
+ * Secrets are stored with:
+ *   service = "agents-cli"
+ *   account = username
+ *   item = the secret identifier
+ */
+import type { KeychainBackend } from './index.js';
+/**
+ * secret-tool lookup attributes:
+ *   service=agents-cli account=<user> item=<itemName>
+ */
+export declare function hasSecretToolToken(item: string): boolean;
+export declare function getSecretToolToken(item: string): string;
+export declare function setSecretToolToken(item: string, value: string): void;
+export declare function deleteSecretToolToken(item: string): boolean;
+/**
+ * List secrets by prefix. secret-tool doesn't have a list command,
+ * so we use secret-tool search which outputs in a specific format.
+ */
+export declare function listSecretToolItems(prefix: string): string[];
+/** KeychainBackend implementation for Linux using secret-tool */
+export declare const linuxBackend: KeychainBackend;

package/dist/lib/secrets/linux.js

@@ -0,0 +1,161 @@
+/**
+ * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
+ *
+ * Uses `secret-tool` CLI which is part of libsecret-tools package.
+ * On Ubuntu: apt install libsecret-tools
+ *
+ * Secrets are stored with:
+ *   service = "agents-cli"
+ *   account = username
+ *   item = the secret identifier
+ */
+import { spawnSync } from 'child_process';
+import * as os from 'os';
+const SERVICE = 'agents-cli';
+function secretToolAvailable() {
+    const result = spawnSync('which', ['secret-tool'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0;
+}
+let checkedAvailability = false;
+let isAvailable = false;
+function ensureSecretTool() {
+    if (!checkedAvailability) {
+        isAvailable = secretToolAvailable();
+        checkedAvailability = true;
+    }
+    if (!isAvailable) {
+        throw new Error('secret-tool not found. Install libsecret-tools:\n' +
+            '  Ubuntu/Debian: sudo apt install libsecret-tools\n' +
+            '  Fedora: sudo dnf install libsecret\n' +
+            '  Arch: sudo pacman -S libsecret');
+    }
+}
+/**
+ * secret-tool lookup attributes:
+ *   service=agents-cli account=<user> item=<itemName>
+ */
+export function hasSecretToolToken(item) {
+    ensureSecretTool();
+    const user = os.userInfo().username;
+    const result = spawnSync('secret-tool', [
+        'lookup',
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return result.status === 0 && result.stdout?.toString().trim().length > 0;
+}
+export function getSecretToolToken(item) {
+    ensureSecretTool();
+    const user = os.userInfo().username;
+    const result = spawnSync('secret-tool', [
+        'lookup',
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        throw new Error(`Secret '${item}' not found in keyring.`);
+    }
+    const token = result.stdout?.toString().trim();
+    if (!token) {
+        throw new Error(`Secret '${item}' exists but is empty.`);
+    }
+    return token;
+}
+export function setSecretToolToken(item, value) {
+    ensureSecretTool();
+    if (!value || !value.trim())
+        throw new Error('Secret value is empty.');
+    const user = os.userInfo().username;
+    const label = `agents-cli: ${item}`;
+    // secret-tool store reads value from stdin
+    const result = spawnSync('secret-tool', [
+        'store',
+        '--label', label,
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        input: value,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const stderr = result.stderr?.toString().trim();
+        throw new Error(`Failed to store secret '${item}': ${stderr || 'unknown error'}\n` +
+            'Make sure GNOME Keyring or another Secret Service provider is running.');
+    }
+}
+export function deleteSecretToolToken(item) {
+    ensureSecretTool();
+    const user = os.userInfo().username;
+    const result = spawnSync('secret-tool', [
+        'clear',
+        'service', SERVICE,
+        'account', user,
+        'item', item,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // secret-tool clear returns 0 whether the item existed or not.
+    // This matches the macOS behavior where delete is idempotent.
+    return result.status === 0;
+}
+/**
+ * List secrets by prefix. secret-tool doesn't have a list command,
+ * so we use secret-tool search which outputs in a specific format.
+ */
+export function listSecretToolItems(prefix) {
+    ensureSecretTool();
+    // secret-tool search outputs attributes, one item per block
+    const result = spawnSync('secret-tool', [
+        'search',
+        '--all',
+        'service', SERVICE,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        return [];
+    }
+    const output = result.stdout?.toString() || '';
+    const items = [];
+    // Parse output format:
+    // [/org/freedesktop/secrets/collection/login/1]
+    // label = agents-cli: myitem
+    // ...
+    // attribute.item = myitem
+    const itemRegex = /attribute\.item\s*=\s*(.+)/g;
+    let match;
+    while ((match = itemRegex.exec(output)) !== null) {
+        const itemName = match[1].trim();
+        if (itemName.startsWith(prefix)) {
+            items.push(itemName);
+        }
+    }
+    return [...new Set(items)]; // dedupe
+}
+/** KeychainBackend implementation for Linux using secret-tool */
+export const linuxBackend = {
+    has(item, _sync) {
+        return hasSecretToolToken(item);
+    },
+    get(item, _sync) {
+        return getSecretToolToken(item);
+    },
+    set(item, value, _sync) {
+        setSecretToolToken(item, value);
+    },
+    delete(item, _sync) {
+        return deleteSecretToolToken(item);
+    },
+    list(prefix) {
+        return listSecretToolItems(prefix);
+    },
+};

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

@@ -137,3 +137,7 @@ export declare function getRowCount(): {
     sessions: number;
     textRows: number;
 };
+/** Count sessions older than the given timestamp (for dry-run previews). */
+export declare function countSessionsOlderThan(cutoffMs: number): number;
+/** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
+export declare function deleteSessionsOlderThan(cutoffMs: number): number;

package/dist/lib/session/db.js

@@ -638,3 +638,29 @@ export function getRowCount() {
     const textRows = db.prepare(`SELECT COUNT(*) AS c FROM session_text`).get().c;
     return { sessions, textRows };
 }
+/** Count sessions older than the given timestamp (for dry-run previews). */
+export function countSessionsOlderThan(cutoffMs) {
+    const db = getDB();
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM sessions WHERE timestamp < ?`).get(cutoffIso);
+    return row.n;
+}
+/** Delete sessions older than the given timestamp. Returns the number of rows deleted. */
+export function deleteSessionsOlderThan(cutoffMs) {
+    const db = getDB();
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const rows = db.prepare(`SELECT id, file_path FROM sessions WHERE timestamp < ?`).all(cutoffIso);
+    if (rows.length === 0)
+        return 0;
+    const txn = db.transaction(() => {
+        for (const { id, file_path } of rows) {
+            db.prepare(`DELETE FROM session_text WHERE session_id = ?`).run(id);
+            db.prepare(`DELETE FROM sessions WHERE id = ?`).run(id);
+            if (file_path) {
+                db.prepare(`DELETE FROM scan_ledger WHERE file_path = ?`).run(canonicalLedgerKey(file_path));
+            }
+        }
+    });
+    txn();
+    return rows.length;
+}

package/dist/lib/usage.d.ts

@@ -79,7 +79,7 @@ export declare function getUsageInfoForIdentity(input: UsageIdentityInput): Prom
 export declare function formatUsageSummary(plan: string | null, snapshot: UsageSnapshot | null, planWidth?: number): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
-/** Load Claude OAuth credentials from the macOS Keychain. */
+/** Load Claude OAuth credentials from the system keychain/keyring. */
 export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
 /**
  * Derive the Keychain service name for a Claude home directory.

package/dist/lib/usage.js

@@ -15,6 +15,7 @@ import * as readline from 'readline';
 import { promisify } from 'util';
 import chalk from 'chalk';
 import { walkForFiles } from './fs-walk.js';
+import { getKeychainToken, setKeychainToken, deleteKeychainToken, } from './secrets/index.js';
 import { getAgentsDir } from './state.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
@@ -343,27 +344,15 @@ function normalizeClaudeWindow(window, key, label, shortLabel) {
         windowMinutes: inferWindowMinutes(key),
     };
 }
-let warnedNonDarwin = false;
-/** Load Claude OAuth credentials from the macOS Keychain. */
+/** Load Claude OAuth credentials from the system keychain/keyring. */
 export async function loadClaudeOauth(home) {
-    if (process.platform !== 'darwin') {
-        if (!warnedNonDarwin && process.stderr.isTTY) {
-            process.stderr.write('[agents] Usage tracking requires macOS Keychain. Skipped on this platform.\n');
-            warnedNonDarwin = true;
-        }
+    // Windows not yet supported
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
         return null;
     }
     try {
-        const account = os.userInfo().username;
-        const { stdout } = await execFileAsync('security', [
-            'find-generic-password',
-            '-a',
-            account,
-            '-s',
-            // Managed Claude homes must stay pinned to their own service name.
-            getClaudeKeychainService(home),
-            '-w',
-        ]);
+        const service = getClaudeKeychainService(home);
+        const stdout = getKeychainToken(service);
         const payload = JSON.parse(stdout.trim());
         if (typeof payload?.claudeAiOauth?.accessToken !== 'string')
             return null;
@@ -380,27 +369,20 @@ export async function loadClaudeOauth(home) {
     }
 }
 /**
- * Save Claude OAuth credentials to the macOS Keychain.
+ * Save Claude OAuth credentials to the system keychain/keyring.
  * Reads the existing payload, merges the new OAuth fields, and writes back.
  */
 async function saveClaudeOauth(home, credentials) {
-    if (process.platform !== 'darwin') {
+    // Windows not yet supported
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
         return false;
     }
     try {
-        const account = os.userInfo().username;
         const service = getClaudeKeychainService(home);
         // Read existing payload to preserve other fields
         let existingPayload = {};
         try {
-            const { stdout } = await execFileAsync('security', [
-                'find-generic-password',
-                '-a',
-                account,
-                '-s',
-                service,
-                '-w',
-            ]);
+            const stdout = getKeychainToken(service);
             existingPayload = JSON.parse(stdout.trim());
         }
         catch {
@@ -418,29 +400,14 @@ async function saveClaudeOauth(home, credentials) {
             },
         };
         const payloadJson = JSON.stringify(newPayload);
-        // Delete existing entry first (security add-generic-password -U can fail)
+        // Delete existing entry first, then add updated entry
         try {
-            await execFileAsync('security', [
-                'delete-generic-password',
-                '-a',
-                account,
-                '-s',
-                service,
-            ]);
+            deleteKeychainToken(service);
         }
         catch {
             // Entry might not exist, ignore
         }
-        // Add updated entry
-        await execFileAsync('security', [
-            'add-generic-password',
-            '-a',
-            account,
-            '-s',
-            service,
-            '-w',
-            payloadJson,
-        ]);
+        setKeychainToken(service, payloadJson);
         return true;
     }
     catch {

package/dist/lib/versions.js

@@ -945,6 +945,17 @@ export async function installVersion(agent, version, onProgress) {
         throw new Error(`Invalid version: ${JSON.stringify(version)}`);
     }
     try {
+        // Check npm is available
+        try {
+            await execFileAsync('which', ['npm']);
+        }
+        catch {
+            return {
+                success: false,
+                installedVersion: version,
+                error: 'npm is not installed. Install Node.js and npm first: https://nodejs.org/',
+            };
+        }
         onProgress?.(`Installing ${packageSpec}...`);
         const { stdout } = await execFileAsync('npm', ['install', packageSpec], { cwd: versionDir });
         // Determine the actual installed version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.14.7",
+  "version": "1.15.0",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",