@phnx-labs/agents-cli 1.20.5 → 1.20.6

package/dist/commands/view.js

@@ -15,6 +15,7 @@ import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
+import { resolveRunDefaults } from '../lib/run-defaults.js';
 import { listProfiles, profileSummary } from '../lib/profiles.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { confirm } from '@inquirer/prompts';
@@ -113,6 +114,29 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
+const SECTION_KEYS = ['commands', 'skills', 'mcp', 'workflows', 'plugins', 'rules', 'hooks', 'promptcuts'];
+/**
+ * Decide whether a section should render given the filter. If no flags are set,
+ * everything renders (current behavior). If any flag is set, only those sections
+ * render — flags are additive.
+ */
+function shouldRenderSection(key, filter) {
+    if (!filter)
+        return true;
+    const anySet = SECTION_KEYS.some((k) => filter[k]);
+    if (!anySet)
+        return true;
+    return filter[key] === true;
+}
+/** Trim a description to a column-friendly snippet. Strips newlines, collapses whitespace. */
+function summarizeDescription(desc, maxLen = 80) {
+    if (!desc)
+        return '';
+    const cleaned = desc.replace(/\s+/g, ' ').trim();
+    if (cleaned.length <= maxLen)
+        return cleaned;
+    return cleaned.slice(0, maxLen - 1).trimEnd() + '…';
+}
 function getProfileSummaries(filterAgentId) {
     return listProfiles()
         .filter((profile) => !filterAgentId || profile.host.agent === filterAgentId)
@@ -338,6 +362,12 @@ async function showInstalledVersions(filterAgentId) {
                 // Otherwise it reflects install time (misleading "just now" for fresh installs).
                 const activeStr = vInfo && hasEmail ? formatLastActive(vInfo.lastActive) : '';
                 const hasActive = activeStr.length > 0;
+                const runDefaults = resolveRunDefaults(agentId, version);
+                const runDefaultBits = [];
+                if (runDefaults.mode)
+                    runDefaultBits.push(`mode:${runDefaults.mode}`);
+                if (runDefaults.model)
+                    runDefaultBits.push(`model:${runDefaults.model}`);
                 if (!hasEmail && !hasUsage) {
                     // Installed but never signed in
                     parts.push(chalk.gray('(not signed in — run ' + agent.cliCommand + ' to log in)'));
@@ -359,6 +389,9 @@ async function showInstalledVersions(filterAgentId) {
                     if (hasActive)
                         parts.push(activeStr);
                 }
+                if (runDefaultBits.length > 0) {
+                    parts.push(chalk.gray(`run ${runDefaultBits.join(' ')}`));
+                }
                 console.log(parts.join('  '));
                 if (showPaths) {
                     const versionDir = getVersionDir(agentId, version);
@@ -568,7 +601,7 @@ async function showInstalledVersions(filterAgentId) {
  * Show detailed resources for a specific agent version.
  * Called when: `agents view claude@2.0.65` or `agents view claude@default`
  */
-async function showAgentResources(agentId, requestedVersion) {
+async function showAgentResources(agentId, requestedVersion, filter) {
     const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
     const cwd = process.cwd();
     const agentsDir = getAgentsDir();
@@ -660,6 +693,8 @@ async function showAgentResources(agentId, requestedVersion) {
         })),
         skills: resources.skills.map(r => ({
             ...r,
+            // ruleCount of 0 is noise — every skill has 0 unless it ships subrules, which is rare.
+            ruleCount: r.ruleCount && r.ruleCount > 0 ? r.ruleCount : undefined,
             syncState: r.scope === 'project' ? undefined : getSyncState(r.name, 'skills', skillsSync),
         })),
         skillErrors: resources.skillErrors,
@@ -705,7 +740,9 @@ async function showAgentResources(agentId, requestedVersion) {
                     : chalk.gray('[system]');
             display += ` ${sourceTag}`;
             const syncStr = r.syncState ? chalk.gray(` [${r.syncState}]`) : '';
-            console.log(`    ${display}${syncStr}`);
+            const descSnippet = summarizeDescription(r.description);
+            const descStr = descSnippet ? chalk.gray(`  ${descSnippet}`) : '';
+            console.log(`    ${display}${syncStr}${descStr}`);
         }
     }
     // Render promptcuts (cross-agent, not per-version). Shortcuts are layered
@@ -722,43 +759,53 @@ async function showAgentResources(agentId, requestedVersion) {
         const label = `${count} shortcut${count === 1 ? '' : 's'}`;
         console.log(`  ${chalk.green(label).padEnd(24)} ${chalk.gray(formatPath(getEffectivePromptcutsPath(), cwd))}`);
     }
-    // 1. Agent CLI info
-    console.log(chalk.bold('Agent CLIs\n'));
-    const accountInfo = await getAccountInfo(agentId, home);
-    const usageInfo = await getUsageInfoForIdentity({
-        agentId,
-        home,
-        cliVersion: version,
-        info: accountInfo,
-    });
-    const emailStr = accountInfo.email ? chalk.cyan(`  ${accountInfo.email}`) : '';
-    const status = chalk.green(version);
-    const usageStr = formatUsageSummary(accountInfo.plan, null);
-    const usagePart = usageStr ? `  ${usageStr}` : '';
-    console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${emailStr}${usagePart}`);
-    const usageLines = formatUsageSection(usageInfo);
-    if (usageLines.length > 0) {
-        console.log();
-        for (const line of usageLines) {
-            console.log(line);
+    const anyFilterSet = filter && SECTION_KEYS.some((k) => filter[k]);
+    // 1. Agent CLI info — skip the header entirely when the user asked for a
+    // specific section. They want "nothing more or less."
+    if (!anyFilterSet) {
+        console.log(chalk.bold('Agent CLIs\n'));
+        const accountInfo = await getAccountInfo(agentId, home);
+        const usageInfo = await getUsageInfoForIdentity({
+            agentId,
+            home,
+            cliVersion: version,
+            info: accountInfo,
+        });
+        const emailStr = accountInfo.email ? chalk.cyan(`  ${accountInfo.email}`) : '';
+        const status = chalk.green(version);
+        const usageStr = formatUsageSummary(accountInfo.plan, null);
+        const usagePart = usageStr ? `  ${usageStr}` : '';
+        console.log(`  ${colorAgent(agentId)(AGENTS[agentId].name.padEnd(14))} ${status}${emailStr}${usagePart}`);
+        const usageLines = formatUsageSection(usageInfo);
+        if (usageLines.length > 0) {
+            console.log();
+            for (const line of usageLines) {
+                console.log(line);
+            }
         }
     }
     // 2. Resources
-    renderSection('Commands', agentData.commands);
-    renderSection('Skills', agentData.skills);
-    // Show skill parse errors if any
-    if (agentData.skillErrors.length > 0) {
-        console.log(`\n  ${chalk.red('Skill Errors')}:`);
-        for (const err of agentData.skillErrors) {
-            console.log(`    ${chalk.red(err.name.padEnd(20))} ${chalk.gray(err.error)}`);
-            console.log(`      ${chalk.gray(formatPath(err.path, cwd))}`);
+    if (shouldRenderSection('commands', filter)) {
+        renderSection('Commands', agentData.commands);
+    }
+    if (shouldRenderSection('skills', filter)) {
+        renderSection('Skills', agentData.skills);
+        // Show skill parse errors only when skills section is visible
+        if (agentData.skillErrors.length > 0) {
+            console.log(`\n  ${chalk.red('Skill Errors')}:`);
+            for (const err of agentData.skillErrors) {
+                console.log(`    ${chalk.red(err.name.padEnd(20))} ${chalk.gray(err.error)}`);
+                console.log(`      ${chalk.gray(formatPath(err.path, cwd))}`);
+            }
         }
     }
-    renderSection('MCP Servers', agentData.mcp);
-    if (isCapable(agentId, 'workflows')) {
+    if (shouldRenderSection('mcp', filter)) {
+        renderSection('MCP Servers', agentData.mcp);
+    }
+    if (shouldRenderSection('workflows', filter) && isCapable(agentId, 'workflows')) {
         renderSection('Workflows', agentData.workflows);
     }
-    if (isCapable(agentId, 'plugins')) {
+    if (shouldRenderSection('plugins', filter) && isCapable(agentId, 'plugins')) {
         const plugins = discoverPlugins().filter(p => pluginSupportsAgent(p, agentId));
         console.log(chalk.bold('\nPlugins\n'));
         if (plugins.length === 0) {
@@ -847,11 +894,18 @@ async function showAgentResources(agentId, requestedVersion) {
             }
         }
     }
-    renderRulesSection();
-    renderSection('Hooks', agentData.hooks);
-    renderPromptcuts();
-    // Show legend at the end if git repo exists
-    if (hasGitRepo) {
+    if (shouldRenderSection('rules', filter)) {
+        renderRulesSection();
+    }
+    if (shouldRenderSection('hooks', filter)) {
+        renderSection('Hooks', agentData.hooks);
+    }
+    if (shouldRenderSection('promptcuts', filter)) {
+        renderPromptcuts();
+    }
+    // Show legend at the end if git repo exists and we showed all sections.
+    // Filtered single-section views skip it — noise for promptcuts or plugins.
+    if (hasGitRepo && !anyFilterSet) {
         console.log();
         console.log(chalk.gray('Legend:'), chalk.green('Tracked'), chalk.blue('Local-only'), chalk.yellow('Modified'), chalk.red('Deleted'));
     }
@@ -1131,6 +1185,17 @@ export async function viewAction(agentArg, options) {
     const prune = options?.prune === true;
     const yes = options?.yes === true;
     const dryRun = options?.dryRun === true;
+    const filter = {
+        commands: options?.commands,
+        skills: options?.skills,
+        mcp: options?.mcp,
+        workflows: options?.workflows,
+        plugins: options?.plugins,
+        rules: options?.rules,
+        hooks: options?.hooks,
+        promptcuts: options?.promptcuts,
+    };
+    const filterIsSet = SECTION_KEYS.some((k) => filter[k]);
     if (!agentArg) {
         if (prune) {
             await pruneDuplicates(undefined, yes, dryRun);
@@ -1180,7 +1245,12 @@ export async function viewAction(agentArg, options) {
     }
     if (requestedVersion) {
         // Specific version requested: show detailed resources
-        await showAgentResources(agentId, requestedVersion);
+        await showAgentResources(agentId, requestedVersion, filter);
+    }
+    else if (filterIsSet) {
+        // `agents view claude --skills` → fall through to detail view on default.
+        // Section filters only make sense for the per-version detail view.
+        await showAgentResources(agentId, 'default', filter);
     }
     else {
         // Just agent name: show versions for that agent
@@ -1196,6 +1266,14 @@ export function registerViewCommand(program) {
         .option('--prune', 'Remove older installed versions that share an account with a newer installed version. Skips the global default.')
         .option('--dry-run', 'With --prune, show duplicate versions without deleting')
         .option('-y, --yes', 'Skip the prune confirmation prompt.')
+        .option('--commands', 'Show only commands in the detail view.')
+        .option('--skills', 'Show only skills in the detail view.')
+        .option('--mcp', 'Show only MCP servers in the detail view.')
+        .option('--workflows', 'Show only workflows in the detail view.')
+        .option('--plugins', 'Show only plugins in the detail view.')
+        .option('--rules', 'Show only rules in the detail view.')
+        .option('--hooks', 'Show only hooks in the detail view.')
+        .option('--promptcuts', 'Show only promptcuts in the detail view.')
         .addHelpText('after', `
 Examples:
   # Show all installed agents with versions, accounts, and usage
@@ -1216,6 +1294,11 @@ Examples:
   agents view claude --prune
   agents view claude --prune -y
 
+  # Filter the detail view to a single section (combinable)
+  agents view claude@default --skills
+  agents view claude@default --plugins --workflows
+  agents view claude --commands    # implicitly the default version
+
 When to use:
   - Checking which agents are installed and what their default versions are
   - Seeing which account each version is logged into (useful for multi-account setups)

package/dist/index.js

@@ -76,6 +76,7 @@ import { registerDaemonCommands } from './commands/daemon.js';
 import { registerRoutinesCommands } from './commands/routines.js';
 import { registerRunCommand } from './commands/exec.js';
 import { registerModelsCommand } from './commands/models.js';
+import { registerDefaultsCommands } from './commands/defaults.js';
 import { registerPruneCommand } from './commands/prune.js';
 import { registerTrashCommands } from './commands/trash.js';
 import { registerDoctorCommand } from './commands/doctor.js';
@@ -151,6 +152,7 @@ Packages:
 
 Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
+  defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
@@ -217,9 +219,12 @@ async function showWhatsNew(fromVersion, toVersion) {
             const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
             if (versionMatch) {
                 currentVersion = versionMatch[1];
-                const isNewer = currentVersion !== fromVersion &&
-                    compareVersions(currentVersion, fromVersion) > 0;
-                inRelevantSection = isNewer;
+                // Only the range the user actually moved through: (fromVersion, toVersion].
+                // Bounding the top end matters when upgrading to a specific older
+                // version, and guards against a changelog that lists unreleased entries.
+                const inRange = compareVersions(currentVersion, fromVersion) > 0 &&
+                    compareVersions(currentVersion, toVersion) <= 0;
+                inRelevantSection = inRange;
                 if (inRelevantSection) {
                     relevantChanges.push('');
                     relevantChanges.push(chalk.bold(`v${currentVersion}`));
@@ -279,11 +284,14 @@ function saveUpdateCheck(latestVersion) {
     }
 }
 /** Fetch the exact latest npm version plus its registry integrity hash. */
-async function fetchLatestNpmPackageMetadata(timeoutMs = 5000) {
-    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/latest`, {
+async function fetchNpmPackageMetadata(versionOrTag = 'latest', timeoutMs = 5000) {
+    const response = await fetch(`https://registry.npmjs.org/${NPM_PACKAGE_NAME}/${versionOrTag}`, {
         signal: AbortSignal.timeout(timeoutMs),
     });
     if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`${NPM_PACKAGE_NAME}@${versionOrTag} not found on npm`);
+        }
         throw new Error('Could not reach npm registry');
     }
     const data = await response.json();
@@ -338,7 +346,7 @@ async function promptUpgrade(latestVersion) {
         const { spawnSync } = await import('child_process');
         let spinner = ora('Resolving package metadata...').start();
         try {
-            const metadata = await fetchLatestNpmPackageMetadata();
+            const metadata = await fetchNpmPackageMetadata();
             spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${metadata.version}`);
             printResolvedPackage(metadata);
             const approved = await confirm({
@@ -583,6 +591,7 @@ registerPackagesCommands(program);
 registerDaemonCommands(program);
 registerRoutinesCommands(program);
 registerRunCommand(program);
+registerDefaultsCommands(program);
 registerModelsCommand(program);
 registerPruneCommand(program);
 registerTrashCommands(program);
@@ -627,26 +636,31 @@ for (const alias of ['jobs', 'cron']) {
 }
 program
     .command('upgrade')
-    .description('Upgrade agents-cli to the latest version')
+    .description('Upgrade agents-cli to the latest version (or a specific [version])')
+    .argument('[version]', 'Target version or dist-tag to install (default: latest)')
     .option('-y, --yes', 'Install without an interactive confirmation prompt')
-    .action(async (options) => {
-    let spinner = ora('Checking for updates...').start();
+    .action(async (version, options) => {
+    const target = version ?? 'latest';
+    let spinner = ora(version ? `Resolving ${NPM_PACKAGE_NAME}@${target}...` : 'Checking for updates...').start();
     try {
-        const metadata = await fetchLatestNpmPackageMetadata();
-        const latestVersion = metadata.version;
-        if (latestVersion === VERSION) {
-            spinner.succeed(`Already on latest version (${VERSION})`);
+        const metadata = await fetchNpmPackageMetadata(target);
+        const resolvedVersion = metadata.version;
+        if (resolvedVersion === VERSION) {
+            spinner.succeed(`Already on ${VERSION}`);
             return;
         }
-        if (compareVersions(latestVersion, VERSION) <= 0) {
-            spinner.succeed(`Already ahead of latest (${VERSION} >= ${latestVersion})`);
+        // For `latest` (no explicit version) skip when already ahead. When a
+        // version is named explicitly, honor it even if it's a downgrade.
+        if (!version && compareVersions(resolvedVersion, VERSION) <= 0) {
+            spinner.succeed(`Already ahead of latest (${VERSION} >= ${resolvedVersion})`);
             return;
         }
-        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${latestVersion}`);
+        const direction = compareVersions(resolvedVersion, VERSION) < 0 ? 'Downgrade' : 'Upgrade';
+        spinner.succeed(`Resolved ${NPM_PACKAGE_NAME}@${resolvedVersion}`);
         printResolvedPackage(metadata);
         if (isInteractiveTerminal() && !options.yes) {
             const approved = await confirm({
-                message: `Install ${NPM_PACKAGE_NAME}@${latestVersion}?`,
+                message: `Install ${NPM_PACKAGE_NAME}@${resolvedVersion}?`,
                 default: false,
             });
             if (!approved) {
@@ -654,14 +668,17 @@ program
                 return;
             }
         }
-        spinner = ora(`Upgrading ${VERSION} -> ${latestVersion}...`).start();
+        spinner = ora(`${direction === 'Downgrade' ? 'Downgrading' : 'Upgrading'} ${VERSION} -> ${resolvedVersion}...`).start();
         await installResolvedPackage(metadata);
-        spinner.succeed(`Upgraded to ${latestVersion}`);
-        await showWhatsNew(VERSION, latestVersion);
+        spinner.succeed(`${direction}d to ${resolvedVersion}`);
+        // Only show the changelog for a genuine upgrade range.
+        if (compareVersions(resolvedVersion, VERSION) > 0) {
+            await showWhatsNew(VERSION, resolvedVersion);
+        }
     }
     catch (err) {
         spinner.fail('Upgrade failed');
-        console.log(chalk.gray('Run manually: agents upgrade --yes'));
+        console.log(chalk.gray(`Run manually: agents upgrade ${version ? version + ' ' : ''}--yes`));
     }
 });
 registerPullCommand(program);

package/dist/lib/agents.d.ts

@@ -69,12 +69,16 @@ export declare function ensureSkillsDir(agentId: AgentId): void;
  * The agent's config-dir name relative to $HOME — e.g. '.claude',
  * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
  *
- * This is the path segment to join onto a (version) home root when locating an
- * agent's commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong
- * for every agent whose config dir is nested or lives under ~/.config —
- * antigravity (~/.gemini/antigravity-cli), amp (~/.config/amp),
- * goose (~/.config/goose), kimi (~/.kimi-code). Mirrors the shim `configDirName`
- * derivation in shims.ts.
+ * Path segment to join onto a (version) home root when locating an agent's
+ * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
+ * every agent whose config dir is nested or under ~/.config — antigravity
+ * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
+ * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
+ *
+ * Relativized against the module-level HOME constant (the same value used to
+ * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
+ * clean relative name even when HOME is overridden after module load (tests,
+ * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
  */
 export declare function agentConfigDirName(agentId: AgentId): string;
 /** Account identity and billing information extracted from an agent's auth config. */

package/dist/lib/agents.js

@@ -446,13 +446,18 @@ export const AGENTS = {
             rulesImports: true,
         },
     },
+    // Kimi Code CLI (`kimi`) — Moonshot AI coding agent.
+    // Install: `curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash`
+    //    or: `npm install -g @moonshot-ai/kimi-code`
+    // Config: `~/.kimi-code/config.toml`, `~/.kimi-code/mcp.json`,
+    //         `~/.kimi-code/skills/`, `~/.kimi-code/hooks/`
     kimi: {
         id: 'kimi',
         name: 'Kimi',
         color: 'magentaBright',
-        cliCommand: 'kimi-code',
-        npmPackage: '',
-        installScript: '',
+        cliCommand: 'kimi',
+        npmPackage: '@moonshot-ai/kimi-code',
+        installScript: 'curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash',
         configDir: path.join(HOME, '.kimi-code'),
         commandsDir: '',
         commandsSubdir: '',
@@ -465,14 +470,14 @@ export const AGENTS = {
         capabilities: {
             hooks: true,
             mcp: true,
-            allowlist: false,
-            skills: false,
+            allowlist: true,
+            skills: true,
             commands: false,
-            plugins: false,
+            plugins: true,
             subagents: false,
             rules: { file: 'AGENTS.md' },
             workflows: false,
-            modes: ['plan', 'edit', 'skip'],
+            modes: ['plan', 'edit', 'auto', 'skip'],
             rulesImports: false,
         },
     },
@@ -690,15 +695,19 @@ export function ensureSkillsDir(agentId) {
  * The agent's config-dir name relative to $HOME — e.g. '.claude',
  * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
  *
- * This is the path segment to join onto a (version) home root when locating an
- * agent's commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong
- * for every agent whose config dir is nested or lives under ~/.config —
- * antigravity (~/.gemini/antigravity-cli), amp (~/.config/amp),
- * goose (~/.config/goose), kimi (~/.kimi-code). Mirrors the shim `configDirName`
- * derivation in shims.ts.
+ * Path segment to join onto a (version) home root when locating an agent's
+ * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
+ * every agent whose config dir is nested or under ~/.config — antigravity
+ * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
+ * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
+ *
+ * Relativized against the module-level HOME constant (the same value used to
+ * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
+ * clean relative name even when HOME is overridden after module load (tests,
+ * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
  */
 export function agentConfigDirName(agentId) {
-    return path.relative(os.homedir(), AGENTS[agentId].configDir);
+    return path.relative(HOME, AGENTS[agentId].configDir);
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export async function getAccountEmail(agentId, home) {

package/dist/lib/browser/chrome.d.ts

@@ -1,5 +1,15 @@
 import type { ChromeOptions } from './types.js';
 import type { BrowserType } from './types.js';
+/**
+ * True when `binaryPath` is a shebang script rather than a native browser
+ * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
+ * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
+ * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
+ * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
+ * Linux/Unix concept — returns false on Windows/macOS app bundles.
+ */
+export declare function isLauncherScript(binaryPath: string): boolean;
+export declare function resolveBrowserBinary(binaryPath: string): string;
 export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
 /**
  * Walk the per-platform priority list and return the first browser that's

package/dist/lib/browser/chrome.js

@@ -42,12 +42,90 @@ const BROWSER_PATHS = {
         custom: [],
     },
 };
+/**
+ * On Debian/Ubuntu the canonical launchers under `/usr/bin`
+ * (`brave-browser`, `google-chrome`, `chromium`) are not the browser ELF —
+ * they're `#!/bin/bash` wrapper scripts (the upstream Chromium wrapper) that,
+ * as their final step, run the real binary as a NON-exec child:
+ *
+ *     exec < /dev/null
+ *     exec > >(exec cat)
+ *     exec 2> >(exec cat >&2)
+ *     "$HERE/brave" "$@" || true
+ *
+ * That breaks `launchBrowser`'s `--remote-debugging-pipe` transport two ways:
+ * the std-fd sanitization (and the extra `cat` process-substitution children)
+ * disturbs the inherited CDP pipe on fd 3/4, and the pid we record is the
+ * wrapper's, not the browser's. The symptom is `read ECONNRESET` /
+ * `CDP connection closed` right after spawn (issue #229).
+ *
+ * Follow the wrapper to the ELF it execs. The wrapper sets
+ * `HERE="dirname(readlink -f "$0")"` and invokes `"$HERE/<name>"`, so we
+ * resolve the script path, scan for that invocation line, and join the two.
+ * Returns the original path untouched when it's already an ELF, when it's not
+ * a resolvable wrapper, or on any non-Linux platform.
+ */
+function readsAsShebangScript(binaryPath) {
+    let fd;
+    try {
+        fd = fs.openSync(binaryPath, 'r');
+    }
+    catch {
+        return false;
+    }
+    try {
+        const head = Buffer.alloc(2);
+        fs.readSync(fd, head, 0, 2, 0);
+        // ELF binaries start with 0x7f 'E'; shebang scripts with '#!'.
+        return head[0] === 0x23 && head[1] === 0x21;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * True when `binaryPath` is a shebang script rather than a native browser
+ * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
+ * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
+ * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
+ * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
+ * Linux/Unix concept — returns false on Windows/macOS app bundles.
+ */
+export function isLauncherScript(binaryPath) {
+    if (os.platform() === 'win32')
+        return false;
+    return readsAsShebangScript(binaryPath);
+}
+export function resolveBrowserBinary(binaryPath) {
+    if (os.platform() !== 'linux')
+        return binaryPath;
+    // Only shebang scripts need unwrapping; a real ELF passes straight through.
+    if (!readsAsShebangScript(binaryPath))
+        return binaryPath;
+    let script;
+    let realScriptPath;
+    try {
+        realScriptPath = fs.realpathSync(binaryPath);
+        script = fs.readFileSync(realScriptPath, 'utf8');
+    }
+    catch {
+        return binaryPath;
+    }
+    // Match the Chromium wrapper's launch line: `"$HERE/<name>" "$@"`, optionally
+    // prefixed with `exec -a "$0"`. The captured name is the real ELF, sitting in
+    // the same directory as the resolved wrapper.
+    const match = script.match(/"\$HERE\/([A-Za-z0-9._-]+)"\s+"\$@"/);
+    if (!match)
+        return binaryPath;
+    const realBinary = path.join(path.dirname(realScriptPath), match[1]);
+    return fs.existsSync(realBinary) ? realBinary : binaryPath;
+}
 export function findBrowserPath(browserType, customBinary) {
     if (customBinary) {
         if (!fs.existsSync(customBinary)) {
             throw new Error(`Custom binary not found: ${customBinary}`);
         }
-        return customBinary;
+        return resolveBrowserBinary(customBinary);
     }
     if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
@@ -60,9 +138,12 @@ export function findBrowserPath(browserType, customBinary) {
     const candidates = platformPaths[browserType] || [];
     for (const p of candidates) {
         if (fs.existsSync(p)) {
-            return p;
+            return resolveBrowserBinary(p);
         }
     }
+    if (browserType === 'comet' && platform !== 'darwin') {
+        throw new Error('Browser "comet" is macOS-only (Comet is a macOS Chromium fork). Use chrome, chromium, brave, or edge on this platform.');
+    }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
 // Per-platform Chromium-family priority list for "no --profile" auto-pick.
@@ -98,7 +179,7 @@ export function findFirstInstalledBrowser(platform = os.platform()) {
         const candidates = platformPaths[browserType] || [];
         for (const p of candidates) {
             if (fs.existsSync(p)) {
-                return { browserType, binary: p };
+                return { browserType, binary: resolveBrowserBinary(p) };
             }
         }
     }