@phnx-labs/agents-cli 1.20.61 → 1.20.63

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -174,6 +174,8 @@ Run and dispatch:
   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)
+  webhook                         Receive signed GitHub/Linear webhooks for trigger routines
+  funnel                          Expose a webhook receiver through Tailscale Funnel
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
   logs [id]                       Show a run's log — host-dispatch task or session; -f to follow
   browser                         Automate a browser — navigate, click, screenshot, console, network
@@ -702,6 +704,8 @@ async function registerAllEagerCommands() {
     await reg(loadLogs);
     await reg(loadEvents);
     await reg(loadAudit);
+    await reg(loadWebhook);
+    await reg(loadFunnel);
     await reg(loadFeed);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
@@ -875,7 +879,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v12';
+        const sentinelValue = 'v13';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/agents.d.ts

@@ -130,6 +130,32 @@ export interface AccountInfo {
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/**
+ * Antigravity (`agy`) stores its OAuth token via the Go keyring library
+ * (zalando/go-keyring), which is platform-split:
+ *
+ *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
+ *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
+ *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
+ *     mapping of service+user). Prefer this over the file when a keyring
+ *     daemon is running.
+ *   - Linux without Secret Service: file fallback at
+ *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
+ *
+ * Probe the OS keyring for existence after the file check. On macOS,
+ * `security find-generic-password` without `-w` is metadata-only (never
+ * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
+ * (stdout is the secret — discarded, never logged). Cached per process —
+ * the keyring is account-global, so one probe covers every installed version.
+ * Returns false when the platform has no probe (Windows) or the tool is
+ * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
+ */
+export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+} | null;
+/** @internal test hook — clear the per-process keyring probe cache. */
+export declare function __resetAntigravityKeychainCacheForTest(): void;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -291,7 +291,15 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: false, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['edit', 'skip'] }, // allowlist: ~/.cursor/cli-config.json
+        // Subagents: `.cursor/agents/<name>.md` (project) or `~/.cursor/agents/<name>.md`
+        // (user), Markdown with YAML frontmatter (name, description, model, readonly,
+        // is_background — no `color`). Shipped in cursor-agent CLI 2026.01 (Cursor 2.4,
+        // 2026-01-22); cursor-agent uses CalVer build tags (e.g. 2025.11.25-<hash>), so
+        // gate at `>= 2026.1.22`. The `agents sync` path enforces this (versions.ts skips
+        // + warns for pre-2.4 installs); the direct `subagents add --agents cursor` path
+        // writes unconditionally, same as the other since-gated agents.
+        // See transformSubagentForCursor / https://cursor.com/docs/subagents.
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '2026.1.22' }, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['edit', 'skip'] }, // allowlist: ~/.cursor/cli-config.json
     },
     opencode: {
         id: 'opencode',
@@ -329,7 +337,11 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '{{ARGUMENTS}}',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'skip'] },
+        // allowlist: maps blanket (whole-tool) rules to ~/.openclaw/openclaw.json
+        // tools.alsoAllow (allow) / tools.deny (deny). OpenClaw gates at tool
+        // granularity only, so sub-command/path/domain patterns are skipped.
+        // OpenClaw is self-updating (no pinned since), so `true` is correct.
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: false, plugins: true, subagents: true, rules: { file: 'workspace/AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'skip'] },
     },
     copilot: {
         id: 'copilot',
@@ -421,7 +433,12 @@ export const AGENTS = {
         // Plugins: Open Plugins under ~/.agents/plugins/<name>/ (same layout as
         // agents-cli source). Version isolation copies into versionHome/.agents/plugins/.
         // Workflows sync as Goose recipe YAML; permissions sync to permission.yaml.
-        capabilities: { hooks: { since: '1.34.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: { since: '1.25.0' }, commands: false, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: true, memory: false, modes: ['edit'] },
+        // Commands: a Goose slash command is a recipe YAML under
+        // ~/.config/goose/commands/<name>.yaml, registered in ~/.config/goose/config.yaml
+        // under `slash_commands: [{ command, recipe_path }]` (see goose-commands.ts).
+        // Subagents: recipe YAML named agents under ~/.config/goose/agents/<name>.yaml
+        // (goose auto-discovers and delegates to them by name in autonomous mode).
+        capabilities: { hooks: { since: '1.34.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: { since: '1.25.0' }, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: true, memory: false, modes: ['edit'] },
     },
     // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
     // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
@@ -610,16 +627,25 @@ export const AGENTS = {
         instructionsFile: 'MEMORY.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
+        supportsHooks: true,
+        // Plugins: Hermes loads plugins from a flat `~/.hermes/plugins/<name>/` dir
+        // with a `plugin.yaml` manifest; a plugin only loads once its name is in the
+        // `plugins.enabled` allowlist in `~/.hermes/config.yaml` (deny-list
+        // `plugins.disabled` wins). Not the Claude marketplace layout, so it installs
+        // via a flat-copy branch (mirrors goose) plus a YAML allowlist toggle.
+        // See https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins
         capabilities: {
-            hooks: false,
+            // Lifecycle hooks land in ~/.hermes/config.yaml under a `hooks:` block
+            // (YAML, shared with `mcp_servers`); gated to Hermes ≥ 0.11.0 which
+            // introduced the configurable hook runner.
+            hooks: { since: '0.11.0' },
             mcp: true,
             mcpHttp: true,
             mcpHeaders: false,
             allowlist: false,
             skills: true,
             commands: false,
-            plugins: false,
+            plugins: true,
             subagents: false,
             rules: { file: 'MEMORY.md' },
             workflows: false,
@@ -638,14 +664,20 @@ export const AGENTS = {
         npmPackage: '',
         installScript: 'curl -fsSL https://forgecode.dev/cli | sh',
         configDir: path.join(HOME, '.forge'),
-        commandsDir: '',
-        commandsSubdir: '',
+        commandsDir: path.join(HOME, '.forge', 'commands'),
+        commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.forge', 'skills'),
         hooksDir: 'hooks',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
+        // Commands: ForgeCode reads Markdown slash commands from `~/.forge/commands/<name>.md`
+        // (also the shared `~/.agents/commands/`); the filename is the command name.
+        // Subagents: named `.md` agent definitions with YAML frontmatter under
+        // `~/.forge/agents/<name>.md` — same Markdown+frontmatter shape as Droid/Copilot
+        // (no `color` field), so transformSubagentForForge aliases transformSubagentForDroid.
+        // See https://forgecode.dev/docs/commands/ and /docs/agent-definition-guide/.
         capabilities: {
             hooks: false,
             mcp: true,
@@ -653,9 +685,9 @@ export const AGENTS = {
             mcpHeaders: false,
             allowlist: false,
             skills: true,
-            commands: false,
+            commands: true,
             plugins: false,
-            subagents: false,
+            subagents: true,
             rules: { file: 'AGENTS.md' },
             workflows: false,
             memory: false,
@@ -995,31 +1027,69 @@ function decryptDroidCredential(base) {
 }
 let cachedAgyKeychainSignedIn;
 /**
- * Antigravity (`agy`, a Codeium/Windsurf-based CLI) stores its OAuth token in
- * the macOS keychain — service `gemini`, account `antigravity` — NOT a file.
- * The file path (`antigravity-oauth-token`) only exists on Linux, where the Go
- * keyring falls back to disk. Probe the keychain for existence (metadata only;
- * `-w` omitted so it never prompts). Cached per process — the keychain is
- * account-global, so one probe covers every installed version. Returns false on
- * non-macOS (the file path handles those).
+ * Antigravity (`agy`) stores its OAuth token via the Go keyring library
+ * (zalando/go-keyring), which is platform-split:
+ *
+ *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
+ *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
+ *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
+ *     mapping of service+user). Prefer this over the file when a keyring
+ *     daemon is running.
+ *   - Linux without Secret Service: file fallback at
+ *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
+ *
+ * Probe the OS keyring for existence after the file check. On macOS,
+ * `security find-generic-password` without `-w` is metadata-only (never
+ * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
+ * (stdout is the secret — discarded, never logged). Cached per process —
+ * the keyring is account-global, so one probe covers every installed version.
+ * Returns false when the platform has no probe (Windows) or the tool is
+ * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
  */
+export function antigravityOsKeyringProbe(platform = process.platform) {
+    if (platform === 'darwin') {
+        return {
+            cmd: 'security',
+            args: ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'],
+        };
+    }
+    if (platform === 'linux') {
+        // go-keyring secret_service attributes: "service" + "username" (not
+        // "account" — that flag is the macOS security(1) spelling of the same user).
+        return {
+            cmd: 'secret-tool',
+            args: ['lookup', 'service', 'gemini', 'username', 'antigravity'],
+        };
+    }
+    return null;
+}
+/** @internal test hook — clear the per-process keyring probe cache. */
+export function __resetAntigravityKeychainCacheForTest() {
+    cachedAgyKeychainSignedIn = undefined;
+}
 async function antigravityKeychainSignedIn() {
-    if (cachedAgyKeychainSignedIn !== undefined)
-        return cachedAgyKeychainSignedIn;
-    // Test isolation: the real macOS keychain can't be sandboxed per-test, so
-    // allow suites asserting "signed out" to opt out of the probe (same spirit as
-    // AGENTS_REAL_HOME). Not cached, so tests can toggle it.
+    // Test isolation first (before cache): real OS keyrings can't be sandboxed
+    // per-test. Same spirit as AGENTS_REAL_HOME. Not cached, so tests can toggle.
     if (process.env.AGENTS_NO_KEYCHAIN_PROBE === '1')
         return false;
-    if (process.platform !== 'darwin') {
+    if (cachedAgyKeychainSignedIn !== undefined)
+        return cachedAgyKeychainSignedIn;
+    const probe = antigravityOsKeyringProbe();
+    if (!probe) {
         cachedAgyKeychainSignedIn = false;
         return false;
     }
     try {
-        await execFileAsync('security', ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'], { timeout: 3000 });
+        // Discard stdout: Linux secret-tool lookup prints the secret value.
+        await execFileAsync(probe.cmd, probe.args, {
+            timeout: 3000,
+            // encoding so stdout is a string we can drop without ever logging it
+            encoding: 'utf8',
+        });
         cachedAgyKeychainSignedIn = true;
     }
     catch {
+        // Missing tool (ENOENT), missing item, locked collection, timeout → signed out.
         cachedAgyKeychainSignedIn = false;
     }
     return cachedAgyKeychainSignedIn;
@@ -1250,10 +1320,12 @@ export async function getAccountInfo(agentId, home) {
                 // Antigravity (`agy`) stores a consumer Google OAuth grant (access +
                 // refresh token, no id_token) — presence of a refresh token is the only
                 // signed-in signal we can derive without a network call. Storage is
-                // platform-split: on Linux it's a file at
-                // ~/.gemini/antigravity-cli/antigravity-oauth-token; on macOS the Go
-                // keyring puts it in the keychain (service 'gemini', account
-                // 'antigravity'), so no file exists — check both.
+                // platform-split via go-keyring:
+                //   - file ~/.gemini/antigravity-cli/antigravity-oauth-token (Linux
+                //     fallback when no Secret Service is available)
+                //   - macOS keychain / Linux libsecret (service gemini + user
+                //     antigravity) when a keyring daemon is present
+                // Check the file first, then the OS keyring probe.
                 const tokenPath = resolveAccountCredentialPath(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
                 if (tokenPath) {
                     const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));

package/dist/lib/browser/ipc.js

@@ -432,11 +432,12 @@ export class BrowserIPCServer {
                 return { ok: true };
             }
             case 'set-download-path': {
-                if (!request.task || !request.downloadPath) {
-                    return { ok: false, error: 'Task and download path required' };
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
                 }
-                await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
-                return { ok: true };
+                // downloadPath optional: omitted → service defaults to the profile's downloads dir.
+                const resolved = await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
+                return { ok: true, downloadPath: resolved };
             }
             case 'wait-download': {
                 if (!request.task) {

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

@@ -11,6 +11,19 @@ export declare const DEFAULT_BROWSER_PROFILE_NAME = "default";
 export declare function getConfiguredDefaultProfileName(): string | undefined;
 export declare function getBrowserRuntimeDir(): string;
 export declare function getProfileRuntimeDir(name: string): string;
+/**
+ * Default destination for browser downloads for a profile. Set browser-global at
+ * connect time (see BrowserService), so downloads land here even when the agent
+ * never calls `browser download --path`. Keyed by the same composite name as the
+ * runtime dir, so every profile is one self-contained tree.
+ */
+export declare function getProfileDownloadsDir(name: string): string;
+/**
+ * Per-profile directory for a task's captured artifacts (screenshots, PDFs,
+ * recordings). Replaces the legacy global `browser/sessions/<task>/` root — the
+ * one-shot migration in migrate.ts folds old captures into here.
+ */
+export declare function getProfileSessionsDir(name: string, task: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
 /**

package/dist/lib/browser/profiles.js

@@ -19,6 +19,23 @@ export function getBrowserRuntimeDir() {
 export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
+/**
+ * Default destination for browser downloads for a profile. Set browser-global at
+ * connect time (see BrowserService), so downloads land here even when the agent
+ * never calls `browser download --path`. Keyed by the same composite name as the
+ * runtime dir, so every profile is one self-contained tree.
+ */
+export function getProfileDownloadsDir(name) {
+    return path.join(getProfileRuntimeDir(name), 'downloads');
+}
+/**
+ * Per-profile directory for a task's captured artifacts (screenshots, PDFs,
+ * recordings). Replaces the legacy global `browser/sessions/<task>/` root — the
+ * one-shot migration in migrate.ts folds old captures into here.
+ */
+export function getProfileSessionsDir(name, task) {
+    return path.join(getProfileRuntimeDir(name), 'sessions', task);
+}
 function configToProfile(name, config) {
     validateRemoteBrowserBinaries(config);
     return {

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

@@ -226,7 +226,18 @@ export declare class BrowserService {
         timeout?: number;
         tabHint?: string;
     }): Promise<void>;
-    setDownloadPath(taskId: string, downloadPath: string, tabHint?: string): Promise<void>;
+    /**
+     * Point the browser's default download destination at the profile's downloads
+     * dir, browser-global, at connect time. Without this a download the agent never
+     * explicitly routed (`browser download --path`) falls to Chromium's own default
+     * — for an attached user browser, wherever that browser was last configured,
+     * which is how downloads used to escape into random locations. Sent on the root
+     * session (no sessionId) so every current and future tab inherits it. Best
+     * effort: a remote CDP endpoint that doesn't expose the Browser domain must not
+     * fail the whole connect.
+     */
+    private applyDefaultDownloadBehavior;
+    setDownloadPath(taskId: string, downloadPath?: string, tabHint?: string): Promise<string>;
     waitForDownload(taskId: string, timeout?: number): Promise<string>;
     private findTaskBySession;
     shutdown(): Promise<void>;

package/dist/lib/browser/service.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { BrowserCdpConnectionError, CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity, } from './cdp.js';
-import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
+import { getProfile, getProfileRuntimeDir, getProfileDownloadsDir, getProfileSessionsDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH, shellQuote } from './drivers/ssh.js';
@@ -308,7 +308,9 @@ export class BrowserService {
         }
         else if (!conn) {
             conn = await this.connectProfile(effectiveProfile, resolved.target);
+            conn.profileName = composite;
             this.connections.set(composite, conn);
+            await this.applyDefaultDownloadBehavior(conn, composite);
         }
         // Browsers launch with --no-startup-window (session-cookie persistence,
         // see launchBrowser), so a bare `start` with no --url would otherwise
@@ -645,7 +647,7 @@ export class BrowserService {
         return result.result.value;
     }
     async screenshot(taskId, tabHint, outputPath, quality = 'compressed') {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
@@ -678,7 +680,7 @@ export class BrowserService {
             }
             extension = 'jpg';
         }
-        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const sessionsDir = getProfileSessionsDir(profileName, task.name);
         const automaticPath = path.join(sessionsDir, `${Date.now()}.${extension}`);
         const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
@@ -695,7 +697,7 @@ export class BrowserService {
      * — without it, dark-mode pages render on a blank sheet.
      */
     async printToPdf(taskId, tabHint, outputPath) {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
@@ -705,7 +707,7 @@ export class BrowserService {
         const sessionId = await this.getSessionId(conn, target.targetId);
         const { data } = (await conn.cdp.send('Page.printToPDF', { printBackground: true, preferCSSPageSize: true }, sessionId));
         const buffer = Buffer.from(data, 'base64');
-        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
+        const sessionsDir = getProfileSessionsDir(profileName, task.name);
         const automaticPath = path.join(sessionsDir, `${Date.now()}.pdf`);
         const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
@@ -723,7 +725,7 @@ export class BrowserService {
         if (this.recordings.has(taskId)) {
             throw new Error(`Task "${taskId}" is already recording. Call record stop first.`);
         }
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
@@ -739,7 +741,7 @@ export class BrowserService {
             throw new Error('--duration must be between 1 and 3600 seconds');
         if (maxMb < 1 || maxMb > 500)
             throw new Error('--max-mb must be between 1 and 500');
-        const recordingsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name, 'recordings');
+        const recordingsDir = path.join(getProfileSessionsDir(profileName, task.name), 'recordings');
         await fs.promises.mkdir(recordingsDir, { recursive: true });
         const outputPath = path.join(recordingsDir, `${Date.now()}.webm`);
         // Resolve ffmpeg lazily so non-recording paths don't pay the import cost.
@@ -1481,20 +1483,50 @@ export class BrowserService {
         throw new Error(`Wait condition "${type}:${value}" not met within ${timeout}ms`);
     }
     // ─── Downloads ───────────────────────────────────────────────────────────────
+    /**
+     * Point the browser's default download destination at the profile's downloads
+     * dir, browser-global, at connect time. Without this a download the agent never
+     * explicitly routed (`browser download --path`) falls to Chromium's own default
+     * — for an attached user browser, wherever that browser was last configured,
+     * which is how downloads used to escape into random locations. Sent on the root
+     * session (no sessionId) so every current and future tab inherits it. Best
+     * effort: a remote CDP endpoint that doesn't expose the Browser domain must not
+     * fail the whole connect.
+     */
+    async applyDefaultDownloadBehavior(conn, profileName) {
+        const downloadPath = getProfileDownloadsDir(profileName);
+        try {
+            await fs.promises.mkdir(downloadPath, { recursive: true });
+            await conn.cdp.send('Browser.setDownloadBehavior', {
+                behavior: 'allow',
+                downloadPath,
+                eventsEnabled: true,
+            });
+        }
+        catch {
+            // Best effort: a remote CDP endpoint (ssh://, ws(s)://) may not expose the
+            // Browser domain. Downloads then keep the endpoint's own default; the connect
+            // must still succeed.
+        }
+    }
     async setDownloadPath(taskId, downloadPath, tabHint) {
-        const { conn, task } = await this.findTask(taskId);
+        const { conn, task, profileName } = await this.findTask(taskId);
         const shortId = tabHint ? await this.resolveTabHint(conn, task, tabHint) : this.resolveCurrentTab(task);
         const cdpTargetId = this.getCdpTargetId(task, shortId);
         const target = await this.getTarget(conn, cdpTargetId);
         if (!target)
             throw new Error(`Tab ${shortId} not found`);
         const sessionId = await this.getSessionId(conn, target.targetId);
+        // No explicit --path: fall back to the profile's downloads dir, the same
+        // destination already set browser-global at connect (applyDefaultDownloadBehavior).
+        const resolvedPath = downloadPath ?? getProfileDownloadsDir(profileName);
+        await fs.promises.mkdir(resolvedPath, { recursive: true });
         await conn.cdp.send('Browser.setDownloadBehavior', {
             behavior: 'allow',
-            downloadPath,
+            downloadPath: resolvedPath,
             eventsEnabled: true,
         }, sessionId);
-        this.pendingDownloads.set(taskId, { path: downloadPath, completed: false });
+        this.pendingDownloads.set(taskId, { path: resolvedPath, completed: false });
         conn.cdp.on('Browser.downloadProgress', (params) => {
             if (params.state === 'completed') {
                 const dl = this.pendingDownloads.get(taskId);
@@ -1504,6 +1536,7 @@ export class BrowserService {
                 }
             }
         });
+        return resolvedPath;
     }
     async waitForDownload(taskId, timeout = 60000) {
         const start = Date.now();
@@ -1590,11 +1623,13 @@ export class BrowserService {
             pid,
             electron: true,
             targetFilter: profile.targetFilter,
+            profileName: forkName,
             forkedFrom: profile.name,
             tasks: new Map(),
             sessionCache: new Map(),
         };
         this.connections.set(forkName, connection);
+        await this.applyDefaultDownloadBehavior(connection, forkName);
         return { forkName, connection };
     }
     /**
@@ -1776,12 +1811,12 @@ export class BrowserService {
             if (!task) {
                 throw new Error(`Task "${taskId}" not found on profile "${profileName}"`);
             }
-            return { conn, task };
+            return { conn, task, profileName };
         }
-        for (const [, conn] of this.connections) {
+        for (const [key, conn] of this.connections) {
             const task = conn.tasks.get(taskId);
             if (task) {
-                return { conn, task };
+                return { conn, task, profileName: conn.profileName ?? key };
             }
         }
         throw new Error(`Task "${taskId}" not found`);

package/dist/lib/browser/sessions-list.d.ts

@@ -0,0 +1,40 @@
+export type ArtifactKind = 'screenshot' | 'pdf' | 'recording' | 'download';
+export interface BrowserArtifact {
+    kind: ArtifactKind;
+    /** Owning task for session captures; undefined for downloads. */
+    task?: string;
+    name: string;
+    path: string;
+    bytes: number;
+    mtimeMs: number;
+}
+export interface ProfileArtifacts {
+    profile: string;
+    artifacts: BrowserArtifact[];
+}
+/** Every capture for one profile, newest first. */
+export declare function listProfileArtifacts(profile: string): BrowserArtifact[];
+/**
+ * Captures grouped by profile. With `only` set, returns just that profile (even
+ * when empty); otherwise every profile dir on disk that has at least one capture.
+ */
+export declare function listBrowserSessions(only?: string): ProfileArtifacts[];
+/** Human table for the CLI. Returns lines (no trailing newline). */
+export declare function renderBrowserSessions(groups: ProfileArtifacts[]): string;
+/**
+ * Resolve `--open <sel>`: `latest` (newest across the groups) or a filename
+ * substring match. Returns the absolute path, or null if nothing matched.
+ */
+export declare function resolveArtifact(groups: ProfileArtifacts[], selector: string): string | null;
+/** Open a file in the OS default app. Returns true on success. */
+export declare function openArtifact(filePath: string): boolean;
+/**
+ * Shared CLI action for `agents browser sessions` and `agents sessions --browser`.
+ * `open` is the Commander value for `--open [selector]`: undefined when the flag
+ * is absent, `true` when passed bare (defaults to 'latest'), or the selector string.
+ */
+export declare function runBrowserSessions(opts: {
+    profile?: string;
+    open?: string | boolean;
+    json?: boolean;
+}): void;