@phnx-labs/agents-cli 1.16.0 → 1.17.0

package/dist/commands/workflows.js

@@ -0,0 +1,457 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { select, checkbox } from '@inquirer/prompts';
+import { resolveAgentName, agentLabel } from '../lib/agents.js';
+import { cloneRepo } from '../lib/git.js';
+import { WORKFLOW_CAPABLE_AGENTS, discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
+import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, } from './utils.js';
+import { showResourceList, buildTargetsSection, } from './resource-view.js';
+/** Register the `agents workflows` command tree (list, view, add, remove). */
+export function registerWorkflowsCommands(program) {
+    const workflowsCmd = program
+        .command('workflows')
+        .description('Manage multi-agent pipeline workflows (WORKFLOW.md bundles)')
+        .addHelpText('after', `
+Workflows are directory bundles (WORKFLOW.md + subagents/) that define multi-agent pipelines run via:
+  agents run <workflow-name>
+
+Examples:
+  # See what workflows are available
+  agents workflows list
+
+  # Install from GitHub
+  agents workflows add gh:user/workflows
+
+  # Install a local workflow directory
+  agents workflows add ./rdev
+
+  # Remove a workflow
+  agents workflows remove rdev
+`);
+    workflowsCmd
+        .command('list [agent]')
+        .description('Show installed workflows and which agent versions they are synced to')
+        .option('-a, --agent <agent>', 'Filter to a specific agent')
+        .action(async (agentArg, options) => {
+        const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
+        const agentInput = agentArg || options.agent;
+        let filterAgent;
+        let filterVersion;
+        if (agentInput) {
+            const parts = agentInput.split('@');
+            const resolved = resolveAgentName(parts[0]);
+            if (!resolved) {
+                spinner.stop();
+                console.log(chalk.red(`Unknown agent: ${parts[0]}`));
+                process.exit(1);
+            }
+            filterAgent = resolved;
+            filterVersion = parts[1] ? resolveVersionAlias(resolved, parts[1]) : undefined;
+        }
+        const rows = buildWorkflowRows({ filterAgent, filterVersion });
+        spinner.stop();
+        await showResourceList({
+            resourcePlural: 'workflows',
+            resourceSingular: 'workflow',
+            extraLabel: 'Agents',
+            rows,
+            emptyMessage: filterAgent
+                ? `No workflows in central storage for ${agentLabel(filterAgent)}.`
+                : 'No workflows in ~/.agents/workflows/. Add one with: agents workflows add gh:user/repo',
+            centralPath: getUserWorkflowsDir(),
+            filterAgent,
+            filterVersion,
+        });
+    });
+    workflowsCmd
+        .command('add [source]')
+        .description('Install workflows from a source (GitHub, local) or pick from central storage')
+        .option('-a, --agents <list>', 'Targets: claude, claude@2.1.138')
+        .option('-y, --yes', 'Skip confirmation prompts')
+        .addHelpText('after', `
+Examples:
+  # Install from GitHub
+  agents workflows add gh:user/workflows
+
+  # Install a local workflow directory (must contain WORKFLOW.md)
+  agents workflows add ./rdev
+
+  # Install and sync to a specific version
+  agents workflows add gh:user/workflows --agents claude@2.1.138
+`)
+        .action(async (source, options) => {
+        try {
+            let workflows;
+            if (!source) {
+                // Interactive: pick from central storage
+                const installed = listInstalledWorkflows();
+                if (installed.size === 0) {
+                    console.log(chalk.yellow('No workflows in ~/.agents/workflows/'));
+                    console.log(chalk.gray('\nTo add workflows from a repo:'));
+                    console.log(chalk.cyan('  agents workflows add gh:user/repo'));
+                    return;
+                }
+                if (!isInteractiveTerminal()) {
+                    requireInteractiveSelection('Selecting workflows', [
+                        'agents workflows add gh:user/repo',
+                    ]);
+                }
+                const choices = Array.from(installed.values()).map(w => ({
+                    value: w.name,
+                    name: w.frontmatter.description
+                        ? `${w.name}  ${chalk.gray(w.frontmatter.description.slice(0, 50))}`
+                        : w.name,
+                }));
+                const selected = await checkbox({ message: 'Select workflows to sync', choices });
+                if (selected.length === 0) {
+                    console.log(chalk.gray('No workflows selected.'));
+                    return;
+                }
+                workflows = selected.map(name => ({ name, path: installed.get(name).path }));
+            }
+            else {
+                // Fetch from repo or local path
+                const spinner = ora('Fetching workflows...').start();
+                const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
+                    source.startsWith('https://') || source.startsWith('http://');
+                let localPath;
+                if (isGitRepo) {
+                    const result = await cloneRepo(source);
+                    localPath = result.localPath;
+                    spinner.succeed('Repository cloned');
+                }
+                else {
+                    localPath = source.startsWith('~')
+                        ? path.join(os.homedir(), source.slice(1))
+                        : path.resolve(source);
+                    if (!fs.existsSync(localPath)) {
+                        spinner.fail(`Path not found: ${localPath}`);
+                        return;
+                    }
+                    spinner.succeed('Using local path');
+                }
+                const discovered = discoverWorkflowsFromRepo(localPath);
+                if (discovered.length === 0) {
+                    console.log(chalk.yellow('No workflows found (looking for WORKFLOW.md files)'));
+                    return;
+                }
+                console.log(chalk.bold(`\nFound ${discovered.length} workflow(s):`));
+                for (const w of discovered) {
+                    console.log(`\n  ${chalk.cyan(w.name)}: ${w.frontmatter.description || 'no description'}`);
+                    if (w.subagentCount > 0) {
+                        console.log(`    ${chalk.gray(`${w.subagentCount} subagent${w.subagentCount === 1 ? '' : 's'}`)}`);
+                    }
+                }
+                const installSpinner = ora('Installing to central storage...').start();
+                let installed = 0;
+                for (const w of discovered) {
+                    const result = installWorkflowCentrally(w.path, w.name);
+                    if (result.success) {
+                        installed++;
+                    }
+                    else {
+                        installSpinner.stop();
+                        console.log(chalk.red(`\n  Failed to install ${w.name}: ${result.error}`));
+                        installSpinner.start();
+                    }
+                }
+                installSpinner.succeed(`Installed ${installed} workflow(s) to ~/.agents/workflows/`);
+                workflows = discovered.map(w => ({
+                    name: w.name,
+                    path: path.join(getUserWorkflowsDir(), w.name),
+                }));
+            }
+            // Agent/version selection
+            let selectedAgents;
+            let versionSelections;
+            if (options.agents) {
+                const result = resolveAgentVersionTargets(options.agents, WORKFLOW_CAPABLE_AGENTS);
+                selectedAgents = result.selectedAgents;
+                versionSelections = result.versionSelections;
+            }
+            else {
+                const result = await promptAgentVersionSelection(WORKFLOW_CAPABLE_AGENTS, {
+                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                });
+                selectedAgents = result.selectedAgents;
+                versionSelections = result.versionSelections;
+            }
+            if (selectedAgents.length === 0) {
+                console.log(chalk.yellow('\nNo agents selected.'));
+                return;
+            }
+            const syncSpinner = ora('Syncing to agent versions...').start();
+            let synced = 0;
+            const workflowNames = workflows.map(w => w.name);
+            for (const [agentId, versions] of versionSelections) {
+                for (const version of versions) {
+                    syncResourcesToVersion(agentId, version);
+                    recordVersionResources(agentId, version, 'workflows', workflowNames);
+                    synced++;
+                }
+            }
+            if (synced > 0) {
+                syncSpinner.succeed(`Synced to ${synced} agent version(s)`);
+            }
+            else {
+                syncSpinner.info('No version-managed agents to sync');
+            }
+            console.log(chalk.green('\nWorkflows installed.'));
+            console.log(chalk.gray('Run with: agents run <workflow-name>'));
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red('Failed to add workflows'));
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    workflowsCmd
+        .command('remove [name]')
+        .description('Remove a workflow from version homes (interactive picker if no name given)')
+        .addHelpText('after', `
+Examples:
+  # Remove a workflow by name
+  agents workflows remove rdev
+
+  # Interactive picker
+  agents workflows remove
+`)
+        .action(async (name) => {
+        const workflowTargetMap = new Map();
+        for (const { agent, version } of iterWorkflowsCapableVersions()) {
+            const home = getVersionHomePath(agent, version);
+            for (const n of listWorkflowsForAgent(agent, home)) {
+                const existing = workflowTargetMap.get(n);
+                if (existing) {
+                    existing.targets.push({ agent, version });
+                }
+                else {
+                    workflowTargetMap.set(n, { name: n, targets: [{ agent, version }] });
+                }
+            }
+        }
+        let toRemove;
+        if (name) {
+            toRemove = [name];
+        }
+        else {
+            if (workflowTargetMap.size === 0) {
+                console.log(chalk.yellow('No workflows synced to any version.'));
+                return;
+            }
+            if (!isInteractiveTerminal()) {
+                requireInteractiveSelection('Selecting workflows to remove', [
+                    'agents workflows remove rdev',
+                ]);
+            }
+            try {
+                const selected = await checkbox({
+                    message: 'Select workflows to remove',
+                    choices: Array.from(workflowTargetMap.values()).map(w => ({
+                        value: w.name,
+                        name: w.name,
+                    })),
+                });
+                if (selected.length === 0) {
+                    console.log(chalk.gray('No workflows selected.'));
+                    return;
+                }
+                toRemove = selected;
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        let removed = 0;
+        for (const workflowName of toRemove) {
+            const info = workflowTargetMap.get(workflowName);
+            if (!info || info.targets.length === 0) {
+                // Not synced to any version — try removing from central storage directly
+                const result = removeWorkflow(workflowName);
+                if (result.success) {
+                    console.log(`  ${chalk.red('-')} ${workflowName}: removed from central storage`);
+                    removed++;
+                }
+                else {
+                    console.log(chalk.yellow(`  Workflow '${workflowName}' not found.`));
+                }
+                continue;
+            }
+            const removalTargets = info.targets.map(t => ({
+                agent: t.agent,
+                version: t.version,
+                label: `${agentLabel(t.agent)}@${t.version}`,
+            }));
+            const selectedTargets = await promptRemovalTargets(workflowName, removalTargets);
+            if (selectedTargets.length === 0) {
+                console.log(chalk.gray(`  Skipped '${workflowName}'.`));
+                continue;
+            }
+            for (const target of selectedTargets) {
+                const result = removeWorkflowFromVersion(target.agent, target.version, workflowName);
+                if (result.success) {
+                    console.log(`  ${chalk.red('-')} ${target.label}: ${workflowName}`);
+                    removed++;
+                }
+                else if (result.error) {
+                    console.log(`  ${chalk.yellow('!')} ${target.label}: ${result.error}`);
+                }
+            }
+        }
+        if (removed === 0) {
+            console.log(chalk.yellow('No workflows removed.'));
+        }
+        else {
+            console.log(chalk.green(`\nRemoved ${removed} workflow(s) from version homes.`));
+            console.log(chalk.gray('Central source unchanged. Use "agents workflows remove <name>" again to remove from ~/.agents/workflows/.'));
+        }
+    });
+    workflowsCmd
+        .command('view [name]')
+        .description('Read workflow details (description, subagents, model, MCP)')
+        .addHelpText('after', `
+Examples:
+  # View a specific workflow
+  agents workflows view rdev
+
+  # Interactive picker
+  agents workflows view
+`)
+        .action(async (name) => {
+        const installed = listInstalledWorkflows();
+        if (!name) {
+            if (installed.size === 0) {
+                console.log(chalk.yellow('No workflows installed'));
+                return;
+            }
+            if (!isInteractiveTerminal()) {
+                requireInteractiveSelection('Selecting a workflow to view', [
+                    'agents workflows view rdev',
+                ]);
+            }
+            try {
+                name = await select({
+                    message: 'Select a workflow to view',
+                    choices: Array.from(installed.values()).map(w => ({
+                        value: w.name,
+                        name: w.frontmatter.description
+                            ? `${w.name} - ${w.frontmatter.description}`
+                            : w.name,
+                    })),
+                });
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled'));
+                    return;
+                }
+                throw err;
+            }
+        }
+        const workflow = installed.get(name);
+        if (!workflow) {
+            console.log(chalk.yellow(`Workflow '${name}' not found`));
+            return;
+        }
+        const lines = [];
+        const fm = workflow.frontmatter;
+        lines.push(chalk.bold(`\n${fm.name || workflow.name}\n`));
+        if (fm.description)
+            lines.push(`  ${fm.description}`);
+        lines.push('');
+        if (fm.model)
+            lines.push(`  Model:  ${fm.model}`);
+        if (fm.tools?.length)
+            lines.push(`  Tools:  ${fm.tools.join(', ')}`);
+        if (fm.mcpServers?.length)
+            lines.push(`  MCP:    ${fm.mcpServers.join(', ')}`);
+        if (fm.skills?.length)
+            lines.push(`  Skills: ${fm.skills.join(', ')}`);
+        lines.push(`  Path:   ${workflow.path}`);
+        if (fm.allowedAgents?.length) {
+            lines.push(chalk.bold(`\n  Subagents (${workflow.subagentCount}):`));
+            for (const a of fm.allowedAgents) {
+                lines.push(`    ${chalk.cyan(a)}`);
+            }
+        }
+        lines.push('');
+        printWithPager(lines.join('\n'), lines.length);
+    });
+}
+function buildWorkflowRows(opts) {
+    const central = listInstalledWorkflows();
+    if (central.size === 0)
+        return [];
+    const targetPairs = iterWorkflowsCapableVersions({
+        agent: opts.filterAgent,
+        version: opts.filterVersion,
+    });
+    const syncedByTarget = new Map();
+    const defaultByAgent = new Map();
+    for (const { agent, version } of targetPairs) {
+        if (!defaultByAgent.has(agent))
+            defaultByAgent.set(agent, getGlobalDefault(agent));
+        const home = getVersionHomePath(agent, version);
+        syncedByTarget.set(`${agent}@${version}`, new Set(listWorkflowsForAgent(agent, home)));
+    }
+    const rows = [];
+    for (const [name, workflow] of central) {
+        const targets = targetPairs.map(({ agent, version }) => ({
+            agent,
+            version,
+            isDefault: defaultByAgent.get(agent) === version,
+            status: syncedByTarget.get(`${agent}@${version}`)?.has(name) ? 'synced' : 'missing',
+        }));
+        rows.push({
+            name,
+            description: workflow.frontmatter.description,
+            extra: workflow.subagentCount > 0 ? `${workflow.subagentCount}` : '-',
+            targets,
+            buildDetail: () => formatWorkflowDetail(workflow, targets),
+        });
+    }
+    rows.sort((a, b) => {
+        const aSynced = a.targets.filter(t => t.status === 'synced').length;
+        const bSynced = b.targets.filter(t => t.status === 'synced').length;
+        if (aSynced !== bSynced)
+            return bSynced - aSynced;
+        return a.name.localeCompare(b.name);
+    });
+    return rows;
+}
+function formatWorkflowDetail(workflow, targets) {
+    const lines = [];
+    const fm = workflow.frontmatter;
+    lines.push(chalk.bold.cyan(workflow.name));
+    if (fm.description)
+        lines.push(chalk.gray(fm.description));
+    lines.push('');
+    const meta = [];
+    if (fm.model)
+        meta.push(`model ${chalk.white(fm.model)}`);
+    if (fm.mcpServers?.length)
+        meta.push(`${chalk.white(fm.mcpServers.length)} MCP`);
+    if (fm.skills?.length)
+        meta.push(`${chalk.white(fm.skills.length)} skill${fm.skills.length === 1 ? '' : 's'}`);
+    meta.push(`${chalk.white(workflow.subagentCount)} subagent${workflow.subagentCount === 1 ? '' : 's'}`);
+    if (meta.length)
+        lines.push('  ' + meta.join(chalk.gray(' · ')));
+    lines.push('  ' + chalk.gray(workflow.path));
+    lines.push('');
+    lines.push(chalk.bold('  Synced to'));
+    lines.push(buildTargetsSection(targets));
+    return lines.join('\n');
+}

package/dist/index.js

@@ -46,6 +46,7 @@ import { registerTrashCommands } from './commands/trash.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerSubagentsCommands } from './commands/subagents.js';
 import { registerPluginsCommands } from './commands/plugins.js';
+import { registerWorkflowsCommands } from './commands/workflows.js';
 import { registerSyncCommand } from './commands/sync.js';
 import { registerRefreshRulesCommand } from './commands/refresh-rules.js';
 import { registerDriveCommands } from './commands/drive.js';
@@ -60,8 +61,8 @@ import { registerBetaCommands } from './commands/beta.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { isPromptCancelled } from './commands/utils.js';
 import { AGENTS } from './lib/agents.js';
-import { getGlobalDefault } from './lib/versions.js';
-import { addShimsToPath, ensureShimCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
+import { getGlobalDefault, listInstalledVersions } from './lib/versions.js';
+import { addShimsToPath, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, hasAliasShadowingShim, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } from './lib/shims.js';
 const program = new Command();
 program
     .name('agents')
@@ -88,7 +89,8 @@ Agent versions:
   add <agent>[@version]           Install an agent CLI (e.g. agents add codex)
   remove <agent>[@version]        Uninstall a version
   use <agent>@<version>           Set the default version
-  prune [target]                  Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs
+  prune [target]                  Remove orphan resources and older duplicate version installs (targets: commands, sessions, runs, trash)
+  trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
 
 Agent configuration (synced across versions):
@@ -97,7 +99,7 @@ Agent configuration (synced across versions):
   skills                          Knowledge packs (SKILL.md + supporting files)
   mcp                             MCP servers (stdio or HTTP)
   permissions                     Allow/deny rules for tool calls
-  hooks                           Shell scripts that run on agent events
+  hooks                           Shell scripts that run on agent events (hooks.yaml in agents.yaml)
   subagents                       Named sub-agent definitions
   plugins                         Bundles of skills, hooks, and scripts
 
@@ -105,19 +107,30 @@ Packages:
   search <query>                  Find MCP servers and skills in registries
   install <pkg>                   Install from registry (mcp:name, skill:user/repo)
 
-Run agents:
+Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
-  sessions                        Browse and replay past runs
+  sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
+  browser                         Automate a browser — navigate, click, screenshot, console, network
+  pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
-Credentials:
+Credentials and profiles:
   profiles                        Bundles of (host CLI, endpoint, model, auth)
-  secrets                         Keychain-backed env bundles injected at spawn
+  secrets                         Keychain-backed env bundles; use 'secrets exec <bundle> -- <cmd>' to inject into a subprocess
 
-Helpers:
-  beta                            Enable preview features like drive and factory
-  pty                             Drive interactive terminal programs (REPLs, TUIs)
+Diagnostics:
+  doctor [agent[@version]]        Diagnose CLI availability, sync status, and resource divergence
+  usage [agent]                   Show rate-limit and quota usage per agent
+
+Config sync:
+  drive                           Sync session history across machines via rsync
+  pull                            Clone or pull the system repo at ~/.agents-system/
+  repo init --path <dir>          Scaffold your own editable repo from a template
+  repo add <path|gh:user/repo>    Merge an extra repo after the system repo
+
+Beta features:
+  beta                            Enable preview features (factory, drive, and more)
 
 Automation tips:
   Pass explicit names/IDs         Avoid pickers: agents sessions <id> --markdown
@@ -126,11 +139,6 @@ Automation tips:
   Use agent@version targets       e.g. --agents claude@2.1.79,codex@default
   Non-TTY shells apply defaults   Omitted required selections fail with a plain hint
 
-Config sync (portable setup via git):
-  pull                            Clone or pull the system repo at ~/.agents-system/
-  repo init --path <dir>          Scaffold your own editable repo from a template
-  repo add <path|gh:user/repo>    Merge an extra repo after the system repo
-
 Options:
   -V, --version                   Show version number
   -h, --help                      Show help
@@ -335,6 +343,12 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
         if (status !== 'current') {
             createdOrUpdated.push(`${status === 'created' ? 'Created' : 'Updated'} ${AGENTS[agent].cliCommand} shim`);
         }
+        for (const version of listInstalledVersions(agent)) {
+            const aliasStatus = ensureVersionedAliasCurrent(agent, version);
+            if (aliasStatus !== 'current') {
+                createdOrUpdated.push(`${aliasStatus === 'created' ? 'Created' : 'Updated'} ${AGENTS[agent].cliCommand}@${version} alias`);
+            }
+        }
     }
     for (const notice of createdOrUpdated) {
         console.log(chalk.green(notice));
@@ -444,6 +458,7 @@ program
 registerMcpCommands(program);
 registerSubagentsCommands(program);
 registerPluginsCommands(program);
+registerWorkflowsCommands(program);
 registerVersionsCommands(program);
 registerPackagesCommands(program);
 registerDaemonCommands(program);

package/dist/lib/browser/cdp.js

@@ -101,10 +101,13 @@ export function verifyBrowserIdentity(reported, expected, port, host = 'localhos
         return;
     const matches = {
         chrome: ['chrome', 'google-chrome', 'headlesschrome'],
-        chromium: ['chromium', 'headlesschrome'],
-        comet: ['comet'],
-        brave: ['brave', 'brave-browser'],
-        edge: ['edge', 'microsoft-edge', 'msedge'],
+        chromium: ['chromium', 'headlesschrome', 'chrome'],
+        // Comet reports itself as plain "Chrome/<version>" in /json/version — it
+        // doesn't override the Chromium branding. Accept chrome here so attaching
+        // to a Comet instance doesn't trip a false "identity mismatch".
+        comet: ['comet', 'chrome'],
+        brave: ['brave', 'brave-browser', 'chrome'],
+        edge: ['edge', 'microsoft-edge', 'msedge', 'chrome'],
     };
     const accepted = matches[expected] || [expected];
     if (accepted.includes(reported))

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

@@ -14,3 +14,13 @@ export declare function getRunningChromeInfo(profileName: string): {
     port: number;
 } | null;
 export declare function allocatePort(): number;
+export interface PortOccupant {
+    pid: number;
+    command: string;
+}
+/**
+ * Identify the process listening on a TCP port via lsof. Returns null when nothing is bound.
+ * Used for clearer error messages when a profile's configured port is taken by a non-debug
+ * process (e.g. Comet running without --remote-debugging-port).
+ */
+export declare function getPortOccupant(port: number): PortOccupant | null;

package/dist/lib/browser/chrome.js

@@ -69,6 +69,7 @@ export async function launchBrowser(profileName, browserType, port, options = {}
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });
+    const viewport = options.viewport ?? { width: 1512, height: 982 };
     const args = [
         `--remote-debugging-port=${port}`,
         `--user-data-dir=${userDataDir}`,
@@ -77,7 +78,10 @@ export async function launchBrowser(profileName, browserType, port, options = {}
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
         ...(options.headless ? ['--headless=new'] : []),
-        ...(options.viewport ? [`--window-size=${options.viewport.width},${options.viewport.height}`] : []),
+        `--window-size=${viewport.width},${viewport.height}`,
+        ...(viewport.x !== undefined && viewport.y !== undefined
+            ? [`--window-position=${viewport.x},${viewport.y}`]
+            : []),
         ...(options.args || []),
     ];
     let env = { ...process.env };
@@ -150,7 +154,11 @@ function isProcessRunning(pid) {
         process.kill(pid, 0);
         return true;
     }
-    catch {
+    catch (err) {
+        // EPERM means the process exists but we lack permission to signal it —
+        // treat as alive. ESRCH means the process does not exist.
+        if (err && err.code === 'EPERM')
+            return true;
         return false;
     }
 }
@@ -170,3 +178,30 @@ export function allocatePort() {
     }
     throw new Error('No available ports in range 9200-9300');
 }
+/**
+ * Identify the process listening on a TCP port via lsof. Returns null when nothing is bound.
+ * Used for clearer error messages when a profile's configured port is taken by a non-debug
+ * process (e.g. Comet running without --remote-debugging-port).
+ */
+export function getPortOccupant(port) {
+    try {
+        const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fpcn`, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        let pid = 0;
+        let command = '';
+        for (const line of out.split('\n')) {
+            if (line.startsWith('p'))
+                pid = parseInt(line.slice(1), 10) || 0;
+            else if (line.startsWith('c') && !command)
+                command = line.slice(1);
+        }
+        if (!pid)
+            return null;
+        return { pid, command: command || 'unknown' };
+    }
+    catch {
+        return null;
+    }
+}