@phnx-labs/agents-cli 1.18.3 → 1.18.5

package/dist/commands/browser.js

@@ -1,22 +1,64 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
 import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
+import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
+import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
 import { sendIPCRequest } from '../lib/browser/ipc.js';
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
+import { registerCommandGroups } from '../lib/help.js';
+/**
+ * Resolve which browser task a command targets. Order:
+ *   1. `--task <name>` flag (explicit per-command override)
+ *   2. `$AGENTS_BROWSER_TASK` (set once at the start of an agent run)
+ *
+ * Each agent process has its own environment, so the env-var path is safe for
+ * parallel agents — they can't see each other's value.
+ */
+function resolveTaskName(opts) {
+    if (opts.task)
+        return opts.task;
+    const fromEnv = process.env.AGENTS_BROWSER_TASK;
+    if (fromEnv)
+        return fromEnv;
+    console.error('No task specified. Pass --task <name> or set AGENTS_BROWSER_TASK in your shell.');
+    console.error('Tip: T=$(agents browser start --profile <p>) && export AGENTS_BROWSER_TASK=$T');
+    process.exit(1);
+}
+// `-t` is taken by `--tab` on most commands, so `--task` is long-form only.
+// Agents normally set $AGENTS_BROWSER_TASK once and never type this flag.
+const TASK_OPTION_FLAG = '--task <name>';
+const TASK_OPTION_DESC = 'Task name (defaults to $AGENTS_BROWSER_TASK)';
+// Help groups — surfaces the actual mental model an agent follows
+// ("open a session / drive the page / capture evidence / rare extras")
+// instead of an alphabetical dump. Everything not listed falls into a
+// trailing "Other commands" section automatically.
+const BROWSER_HELP_GROUPS = [
+    { title: 'Session lifecycle', names: ['start', 'done', 'status'] },
+    {
+        title: 'Drive the page',
+        names: ['navigate', 'tabs', 'screenshot', 'evaluate', 'click', 'type', 'press', 'wait'],
+    },
+    {
+        title: 'Capture evidence',
+        names: ['console', 'errors', 'requests', 'responsebody', 'record', 'logs'],
+    },
+];
 export function registerBrowserCommand(program) {
     const browser = program
         .command('browser')
         .description('Browser automation via CDP');
     registerProfilesCommands(browser);
     registerTaskCommands(browser);
+    registerCommandGroups(browser, BROWSER_HELP_GROUPS);
 }
 export function registerBrowserSubcommands(program) {
     registerProfilesCommands(program);
     registerTaskCommands(program);
+    registerCommandGroups(program, BROWSER_HELP_GROUPS);
 }
 function registerProfilesCommands(browser) {
     const profiles = browser
@@ -38,7 +80,10 @@ function registerProfilesCommands(browser) {
             console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'DESCRIPTION'.padEnd(38) + 'ENDPOINTS');
             console.log('-'.repeat(92));
             for (const p of allProfiles) {
-                const endpoints = p.endpoints.join(', ');
+                const presets = getEndpointPresets(p);
+                const endpoints = Object.entries(presets)
+                    .map(([name, ep]) => (name.startsWith('endpoint-') ? ep.target : `${name}=${ep.target}`))
+                    .join(', ');
                 const desc = (p.description ?? '').slice(0, 36).padEnd(38);
                 console.log(p.name.padEnd(20) + (p.browser || '-').padEnd(12) + desc + endpoints);
             }
@@ -47,7 +92,10 @@ function registerProfilesCommands(browser) {
             console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'ENDPOINTS');
             console.log('-'.repeat(72));
             for (const p of allProfiles) {
-                const endpoints = p.endpoints.join(', ');
+                const presets = getEndpointPresets(p);
+                const endpoints = Object.entries(presets)
+                    .map(([name, ep]) => (name.startsWith('endpoint-') ? ep.target : `${name}=${ep.target}`))
+                    .join(', ');
                 console.log(p.name.padEnd(20) + (p.browser || '-').padEnd(12) + endpoints);
             }
         }
@@ -61,7 +109,7 @@ function registerProfilesCommands(browser) {
         .option('-s, --secrets <bundle>', 'Secrets bundle to inject')
         .option('-d, --description <text>', 'Profile description')
         .option('--headless', 'Run in headless mode')
-        .option('--window <WxH>', 'Window size, e.g. 1512x982')
+        .option('--window <WxH>', `Window size in CSS pixels (default: ${DEFAULT_VIEWPORT.width}x${DEFAULT_VIEWPORT.height}, MacBook Pro 14")`)
         .option('--position <X,Y>', 'Window position on screen, e.g. 80,80')
         .option('--binary <path>', 'Absolute path to the browser/app binary (required with --browser custom)')
         .option('--electron', 'Treat this profile as an Electron desktop app: never call Target.createTarget; bind to the visible window using --target-filter or the skip-invisible heuristic')
@@ -100,15 +148,16 @@ function registerProfilesCommands(browser) {
             const freePort = await findFreeProfilePort();
             endpoints = [`cdp://127.0.0.1:${freePort}`];
         }
-        // Viewport is mandatory — default to 1512x982 if --window is not provided
+        // Viewport is mandatory — default to MacBook Pro 14" (1512x982) if
+        // --window is not provided. See lib/browser/devices.ts DEFAULT_VIEWPORT.
         let viewport = {
-            width: 1512,
-            height: 982,
+            width: DEFAULT_VIEWPORT.width,
+            height: DEFAULT_VIEWPORT.height,
         };
         if (opts.window) {
             const m = String(opts.window).match(/^(\d+)x(\d+)$/);
             if (!m) {
-                console.error('--window must be WxH, e.g. 1512x982');
+                console.error(`--window must be WxH, e.g. ${DEFAULT_VIEWPORT.width}x${DEFAULT_VIEWPORT.height}`);
                 process.exit(1);
             }
             viewport.width = parseInt(m[1], 10);
@@ -167,9 +216,24 @@ function registerProfilesCommands(browser) {
             console.log(`Target filter: ${profile.targetFilter}`);
         if (profile.description)
             console.log(`Description: ${profile.description}`);
-        console.log(`Endpoints:`);
-        for (const e of profile.endpoints) {
-            console.log(`  - ${e}`);
+        const presets = getEndpointPresets(profile);
+        const defaultName = profile.defaultEndpoint && presets[profile.defaultEndpoint]
+            ? profile.defaultEndpoint
+            : Object.keys(presets)[0];
+        console.log('Endpoints:');
+        for (const [presetName, preset] of Object.entries(presets)) {
+            const marker = presetName === defaultName ? ' (default)' : '';
+            const isLegacy = presetName.startsWith('endpoint-');
+            console.log(`  - ${isLegacy ? preset.target : `${presetName}: ${preset.target}`}${marker}`);
+            if (preset.binary)
+                console.log(`      binary: ${preset.binary}`);
+            if (preset.targetFilter)
+                console.log(`      targetFilter: ${preset.targetFilter}`);
+        }
+        if (profile.viewport) {
+            const v = profile.viewport;
+            const pos = v.x !== undefined && v.y !== undefined ? ` @ ${v.x},${v.y}` : '';
+            console.log(`Viewport: ${v.width}×${v.height}${pos}`);
         }
         if (profile.secrets)
             console.log(`Secrets: ${profile.secrets}`);
@@ -178,31 +242,32 @@ function registerProfilesCommands(browser) {
     });
     profiles
         .command('delete <name>')
-        .description('Delete a browser profile')
-        .action(async (name) => {
+        .description('Delete a browser profile (drops YAML config + all cached runtime dirs)')
+        .option('--keep-cache', "Leave ~/.agents/.cache/browser/<name>* dirs in place (don't wipe chrome-data)")
+        .action(async (name, opts) => {
         await deleteProfile(name);
-        console.log(`Deleted profile: ${name}`);
-    });
-    profiles
-        .command('launch <name>')
-        .description('Start (or attach to) the profile\'s browser without creating a task')
-        .action(async (name) => {
-        const profile = await getProfile(name);
-        if (!profile) {
-            console.error(`Profile "${name}" not found`);
-            process.exit(1);
-        }
-        const response = await sendIPCRequest({
-            action: 'launch-profile',
-            profile: name,
-        });
-        if (!response.ok) {
-            console.error(response.error);
-            process.exit(1);
+        // The composite naming change introduced multiple cache dirs per
+        // profile (`<name>`, `<name>@endpoint-0`, …). Sweep them all unless
+        // the user explicitly wants the chrome-data preserved (e.g. for
+        // re-import into a freshly-created profile of the same name).
+        let removed = 0;
+        if (!opts.keepCache) {
+            const cacheDirs = listProfileCacheDirs(name);
+            removed = cacheDirs.length;
+            for (const dir of cacheDirs) {
+                // `removeProfileCache` operates by profile-name; for the
+                // composite dirs we already have the absolute path. Use rmSync
+                // directly so we don't depend on naming round-trips.
+                try {
+                    fs.rmSync(dir, { recursive: true, force: true });
+                }
+                catch { /* ignore */ }
+            }
+            // The canonical wipe also covers the legacy dir if present.
+            removeProfileCache(name);
         }
-        const pidLabel = response.pid ? `pid ${response.pid}` : 'attached';
-        console.log(`Launched "${name}" on port ${response.port} (${pidLabel})`);
-        console.log(`Next: agents browser start --profile ${name} --url <url>`);
+        console.log(`Deleted profile: ${name}` +
+            (removed > 0 ? ` (and ${removed} cache dir${removed === 1 ? '' : 's'})` : ''));
     });
     profiles
         .command('doctor <name>')
@@ -226,12 +291,31 @@ function registerProfilesCommands(browser) {
                 detail: err instanceof Error ? err.message : String(err),
             });
         }
-        // 2. Configured port: free, or already serving the expected browser?
+        // 2. Configured port. For local cdp:// we check the local port. For
+        //    ssh:// the port lives on a remote host — doctor's previous
+        //    behavior was to lsof the LOCAL port number, which was both
+        //    misleading and arbitrary (after the SSH-binds-locally change
+        //    the local port now matches the remote, so a positive answer
+        //    is plausible; but doctor still shouldn't report on remote
+        //    state without an --remote-probe explicitly).
         const port = extractConfiguredPort(profile);
         let attachingToExistingBrowser = false;
+        const firstEndpointTarget = (() => {
+            const presets = getEndpointPresets(profile);
+            const first = Object.keys(presets)[0];
+            return first ? presets[first].target : undefined;
+        })();
+        const isSshEndpoint = firstEndpointTarget?.startsWith('ssh://') ?? false;
         if (port === undefined) {
             checks.push({ label: 'port', ok: true, detail: 'no port in endpoint' });
         }
+        else if (isSshEndpoint) {
+            checks.push({
+                label: 'port',
+                ok: true,
+                detail: `${port} (remote on ${firstEndpointTarget}) — skipping local check`,
+            });
+        }
         else {
             const occupant = getPortOccupant(port);
             if (!occupant) {
@@ -302,7 +386,9 @@ function registerProfilesCommands(browser) {
                     checks.push({
                         label: 'onboarding',
                         ok: false,
-                        detail: 'Local State is empty — run `agents browser profiles prime ' + name + '`',
+                        detail: 'Local State is empty — run `agents browser start --profile ' +
+                            name +
+                            '` and finish any first-run screens before automating',
                     });
                 }
             }
@@ -310,7 +396,9 @@ function registerProfilesCommands(browser) {
                 checks.push({
                     label: 'onboarding',
                     ok: false,
-                    detail: 'Not primed yet — run `agents browser profiles prime ' + name + '`',
+                    detail: 'Not initialized yet — run `agents browser start --profile ' +
+                        name +
+                        '` and finish any first-run screens before automating',
                 });
             }
         }
@@ -322,63 +410,68 @@ function registerProfilesCommands(browser) {
         if (!allOk)
             process.exit(1);
     });
-    profiles
-        .command('prime <name>')
-        .description('Launch the profile so you can complete first-run onboarding interactively')
-        .action(async (name) => {
-        const profile = await getProfile(name);
-        if (!profile) {
-            console.error(`Profile "${name}" not found`);
-            process.exit(1);
-        }
-        const response = await sendIPCRequest({
-            action: 'launch-profile',
-            profile: name,
-        });
-        if (!response.ok) {
-            console.error(response.error);
-            process.exit(1);
-        }
-        const pidLabel = response.pid ? `pid ${response.pid}` : 'attached';
-        console.log(`Launched "${name}" on port ${response.port} (${pidLabel}).`);
-        console.log('');
-        console.log('Finish any first-run / onboarding screens in the browser window');
-        console.log('(welcome, profile setup, default-browser prompt, sign-in, etc.).');
-        console.log('Once you reach a normal browsing surface, this profile is primed');
-        console.log('— its user-data-dir persists across runs, so you only do this once.');
-        console.log('');
-        console.log(`Next: agents browser start --profile ${name} --url <url>`);
-    });
 }
 function registerTaskCommands(browser) {
     browser
         .command('start')
         .description('Start a browser task with a profile')
         .requiredOption('-p, --profile <name>', 'Browser profile to use')
-        .option('-t, --task <name>', 'Task name (auto-generated if omitted)')
+        .option(TASK_OPTION_FLAG, 'Task name (auto-generated if omitted)')
+        .option('-e, --endpoint <name>', 'Endpoint preset (defaults to the profile\'s default)')
         .option('-u, --url <url>', 'Open URL in first tab')
         .action(async (opts) => {
+        // Pre-check the profile locally so we fail fast with a helpful error
+        // instead of round-tripping a generic "Profile not found" through the daemon.
+        const profile = await getProfile(opts.profile);
+        if (!profile) {
+            console.error(`Profile "${opts.profile}" not found.`);
+            const all = await listProfiles();
+            if (all.length > 0) {
+                console.error(`Available profiles: ${all.map((p) => p.name).join(', ')}`);
+            }
+            console.error(`Create one with: agents browser profiles create ${opts.profile} --browser <chrome|comet|chromium|brave|edge|custom>`);
+            process.exit(1);
+        }
+        // Pre-check the endpoint name too — same fail-fast rationale.
+        if (opts.endpoint) {
+            const presets = getEndpointPresets(profile);
+            if (!presets[opts.endpoint]) {
+                console.error(`Endpoint "${opts.endpoint}" not found on profile "${opts.profile}". ` +
+                    `Available: ${Object.keys(presets).join(', ')}`);
+                process.exit(1);
+            }
+        }
         const response = await sendIPCRequest({
             action: 'start',
             profile: opts.profile,
             taskName: opts.task,
             url: opts.url,
+            endpoint: opts.endpoint,
         });
         if (!response.ok) {
             console.error(response.error);
             process.exit(1);
         }
+        // stdout: just the resolved name, one line, no decoration. Lets callers do:
+        //   export AGENTS_BROWSER_TASK=$(agents browser start --profile work)
+        console.log(response.task);
+        // stderr: human-friendly commentary so a TTY user still sees what happened.
+        // Shell substitution captures stdout only, so $(...) stays clean.
         if (opts.url && response.tabId) {
-            console.log(`Started task "${response.task}" with tab ${response.tabId}`);
+            console.error(`Started task "${response.task}" with tab ${response.tabId}`);
         }
         else {
-            console.log(`Started task "${response.task}"`);
+            console.error(`Started task "${response.task}"`);
         }
+        console.error(`Tip: export AGENTS_BROWSER_TASK=${response.task}`);
+        console.error('Try: agents browser screenshot | agents browser console --level error');
     });
     browser
-        .command('done <task>')
+        .command('done')
         .description('Complete a task and close its tabs')
-        .action(async (task) => {
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'done',
             task,
@@ -390,9 +483,24 @@ function registerTaskCommands(browser) {
         console.log(`Completed task: ${task}`);
     });
     browser
-        .command('stop <task>')
-        .description('Stop a browser task and close its tabs')
-        .action(async (task) => {
+        .command('stop')
+        .description('Stop a browser task and close its tabs; with --profile, detach the whole profile (close browser + drop cached connection)')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option('-p, --profile <name>', 'Detach the whole profile (incl. composite "name@endpoint") instead of stopping a single task')
+        .action(async (opts) => {
+        if (opts.profile) {
+            const response = await sendIPCRequest({
+                action: 'stop',
+                profile: opts.profile,
+            });
+            if (!response.ok) {
+                console.error(response.error);
+                process.exit(1);
+            }
+            console.log(`Stopped profile: ${opts.profile}`);
+            return;
+        }
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'stop',
             task,
@@ -404,45 +512,53 @@ function registerTaskCommands(browser) {
         console.log(`Stopped task: ${task}`);
     });
     browser
-        .command('navigate <task> <url>')
+        .command('navigate')
         .description('Navigate current tab to URL (creates tab if none exist)')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .requiredOption('--url <url>', 'URL to navigate to')
         .option('-p, --profile <name>', 'Browser profile (optional if task is unique)')
-        .action(async (task, url, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'navigate',
             task,
-            url,
+            url: opts.url,
             profile: opts.profile,
         });
         if (!response.ok) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log(`Navigated ${response.tabId} to ${url}`);
+        console.log(`Navigated ${response.tabId} to ${opts.url}`);
     });
     // Tab subcommand group
     const tab = browser.command('tab').description('Manage tabs');
     tab
-        .command('add <task> <url>')
+        .command('add')
         .description('Open URL in new tab (becomes current)')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .requiredOption('--url <url>', 'URL to open in the new tab')
         .option('-p, --profile <name>', 'Browser profile')
-        .action(async (task, url, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'tab-add',
             task,
-            url,
+            url: opts.url,
             profile: opts.profile,
         });
         if (!response.ok) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log(`Opened tab ${response.tabId}: ${url}`);
+        console.log(`Opened tab ${response.tabId}: ${opts.url}`);
     });
     tab
-        .command('focus <task> <tabId>')
+        .command('focus <tabId>')
         .description('Switch to tab (by ID, prefix, or URL substring)')
-        .action(async (task, tabId) => {
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .action(async (tabId, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'tab-focus',
             task,
@@ -455,9 +571,11 @@ function registerTaskCommands(browser) {
         console.log(`Focused tab ${response.tabId}`);
     });
     tab
-        .command('close <task> [tabId]')
+        .command('close [tabId]')
         .description('Close tab(s) — omit tabId to close all')
-        .action(async (task, tabId) => {
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .action(async (tabId, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'tab-close',
             task,
@@ -469,11 +587,13 @@ function registerTaskCommands(browser) {
         }
         console.log(tabId ? `Closed tab ${tabId}` : `Closed all tabs for ${task}`);
     });
-    tab
-        .command('list <task>')
-        .description('List tabs for a task')
+    browser
+        .command('tabs')
+        .description('List tabs open for the current task')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('--json', 'Output machine-readable JSON')
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'tab-list',
             task,
@@ -503,27 +623,73 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('screenshot <task> [tabId]')
-        .description('Take a screenshot')
-        .option('-o, --output <path>', 'Output path')
-        .action(async (task, tabId, opts) => {
+        .command('screenshot')
+        .description('Take a screenshot — auto-saved per task; --output only needed when you want a specific path')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('-o, --output <path>', 'Specific output path (otherwise auto-saved under sessions/<task>/)')
+        .option('-q, --quality <mode>', 'compressed (JPEG, capped at ~100 KB — default) or raw (PNG, pixel-faithful)', 'compressed')
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
+        if (opts.quality !== 'compressed' && opts.quality !== 'raw') {
+            console.error('--quality must be "compressed" or "raw"');
+            process.exit(1);
+        }
         const response = await sendIPCRequest({
             action: 'screenshot',
             task,
-            tabId,
+            tabId: opts.tab,
             path: opts.output,
+            quality: opts.quality,
         });
         if (!response.ok) {
             console.error(response.error);
             process.exit(1);
         }
+        // stdout: just the path, so `P=$(agents browser screenshot)` works.
         console.log(response.path);
+        // stderr: human commentary with size + dimensions, so an agent can
+        // see at a glance what was captured without `ls -l && file` round-trips.
+        const size = humanizeBytes(response.bytes);
+        const dims = response.width && response.height ? `${response.width}×${response.height}` : 'unknown size';
+        console.error(`Saved screenshot to ${response.path} (${size}, ${dims})`);
+        // When auto-saving (no --output), surface the directory once so the
+        // agent doesn't have to dirname() the path or guess where files land.
+        if (!opts.output && response.path) {
+            const dir = path.dirname(response.path);
+            console.error(`Tip: auto-saving to ${dir}. Pass --output <path> to choose a path.`);
+        }
     });
     browser
-        .command('evaluate <task> <expression>')
+        .command('evaluate')
         .description('Evaluate JavaScript in current tab')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .action(async (task, expression, opts) => {
+        .option('-e, --expression <js>', 'JavaScript expression to evaluate')
+        .option('-f, --file <path>', 'Path to a .js file whose contents will be evaluated')
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
+        if (opts.expression && opts.file) {
+            console.error('Pass exactly one of --expression or --file');
+            process.exit(1);
+        }
+        let expression;
+        if (opts.file) {
+            try {
+                expression = fs.readFileSync(opts.file, 'utf8');
+            }
+            catch (err) {
+                console.error(`Cannot read --file ${opts.file}: ${err.message}`);
+                process.exit(1);
+            }
+        }
+        else if (opts.expression) {
+            expression = opts.expression;
+        }
+        else {
+            console.error('Pass --expression <js> or --file <path>');
+            process.exit(1);
+        }
         const response = await sendIPCRequest({
             action: 'evaluate',
             task,
@@ -536,6 +702,73 @@ function registerTaskCommands(browser) {
         }
         console.log(JSON.stringify(response.result, null, 2));
     });
+    browser
+        .command('ps')
+        .description('List every browser/electron/tunnel process agents has tracked (alive or stale) — works without the daemon')
+        .option('--json', 'Output machine-readable JSON')
+        .action((opts) => {
+        const snapshots = listAllProfileSnapshots();
+        // Cross-check against what's actually listening locally so we can
+        // surface "port claimed by us but nothing is listening" (= leaked
+        // cache file) and "port listening but not in our records" (= someone
+        // else owns it; a new profile pointing here would collide).
+        const portOwners = new Map();
+        const conflicts = [];
+        for (const s of snapshots) {
+            const port = s.meta?.port;
+            if (!port)
+                continue;
+            const occupant = getPortOccupant(port);
+            if (!occupant) {
+                if (s.pidAlive || s.tunnelAlive) {
+                    conflicts.push(`${s.name}: port ${port} marked active but nothing is listening`);
+                }
+                continue;
+            }
+            const ourPid = s.meta?.tunnelPid && s.meta.kind === 'tunnel'
+                ? s.meta.tunnelPid
+                : s.meta?.pid;
+            if (ourPid && occupant.pid !== ourPid) {
+                conflicts.push(`${s.name}: port ${port} listened on by ${occupant.command} (pid ${occupant.pid}) but our record says pid ${ourPid}`);
+            }
+            portOwners.set(port, occupant);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ snapshots, conflicts }, null, 2));
+            return;
+        }
+        if (snapshots.length === 0) {
+            console.log('No tracked browser state. Run `agents browser start --profile <name>` to spawn one.');
+            return;
+        }
+        console.log('PROFILE                                  KIND      PID    TUNNEL  PORT   ALIVE  TASKS  OWNER');
+        console.log('-----------------------------------------------------------------------------------------------');
+        for (const s of snapshots) {
+            const kind = s.meta?.kind ?? '-';
+            const pid = s.meta?.pid ?? '-';
+            const tunnelPid = s.meta?.tunnelPid ?? '-';
+            const port = s.meta?.port ?? '-';
+            const alive = aliveLabel(s);
+            const owner = s.meta?.daemonPid
+                ? `daemon${s.daemonAlive ? '' : '(dead)'}=${s.meta.daemonPid}`
+                : '-';
+            console.log(`${s.name.padEnd(40)} ${String(kind).padEnd(9)} ${String(pid).padEnd(6)} ${String(tunnelPid).padEnd(7)} ${String(port).padEnd(6)} ${alive.padEnd(6)} ${String(s.taskCount).padEnd(6)} ${owner}`);
+        }
+        if (conflicts.length > 0) {
+            console.log('');
+            console.log('Conflicts / leaks detected:');
+            for (const c of conflicts)
+                console.log(`  - ${c}`);
+            console.log('');
+            console.log('Run `agents browser stop --profile <name>` to clean up a specific profile, or restart the daemon to trigger the orphan reaper.');
+        }
+    });
+    function aliveLabel(s) {
+        const k = s.meta?.kind;
+        if (k === 'tunnel')
+            return s.tunnelAlive ? 'yes' : 'stale';
+        return s.pidAlive ? 'yes' : 'stale';
+    }
     browser
         .command('status')
         .description('Show running browser tasks')
@@ -749,13 +982,15 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('refs <task>')
+        .command('refs')
         .description('Get DOM refs for interactive elements')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--all', 'Include non-interactive elements')
         .option('-l, --limit <n>', 'Max elements (default 500)', '500')
         .option('--json', 'Output machine-readable JSON')
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'refs',
             task,
@@ -779,10 +1014,12 @@ function registerTaskCommands(browser) {
         console.log(response.refs);
     });
     browser
-        .command('click <task> <ref>')
+        .command('click <ref>')
         .description('Click an element by ref')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .action(async (task, ref, opts) => {
+        .action(async (ref, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'click',
             task,
@@ -796,17 +1033,25 @@ function registerTaskCommands(browser) {
         console.log('Clicked');
     });
     browser
-        .command('type <task> <ref> <text>')
+        .command('type <ref>')
         .description('Type text into an element by ref')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .requiredOption('--text <text>', 'Text to type (use quotes for spaces/special chars)')
         .option('--clear', 'Clear editor content before typing')
-        .action(async (task, ref, text, opts) => {
+        .action(async (ref, opts) => {
+        const task = resolveTaskName(opts);
+        const refNum = parseInt(ref, 10);
+        if (!Number.isFinite(refNum)) {
+            console.error(`<ref> must be an integer, got: ${ref}`);
+            process.exit(1);
+        }
         const response = await sendIPCRequest({
             action: 'type',
             task,
             tabId: opts.tab,
-            ref: parseInt(ref, 10),
-            text,
+            ref: refNum,
+            text: opts.text,
             clear: opts.clear,
         });
         if (!response.ok) {
@@ -816,10 +1061,12 @@ function registerTaskCommands(browser) {
         console.log('Typed');
     });
     browser
-        .command('press <task> <key>')
+        .command('press <key>')
         .description('Press a key (Enter, Tab, Escape, etc)')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .action(async (task, key, opts) => {
+        .action(async (key, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'press',
             task,
@@ -833,10 +1080,12 @@ function registerTaskCommands(browser) {
         console.log('Pressed');
     });
     browser
-        .command('hover <task> <ref>')
+        .command('hover <ref>')
         .description('Hover over an element by ref')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .action(async (task, ref, opts) => {
+        .action(async (ref, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'hover',
             task,
@@ -850,18 +1099,30 @@ function registerTaskCommands(browser) {
         console.log('Hovered');
     });
     browser
-        .command('scroll <task> <deltaX> <deltaY>')
-        .description('Scroll the page by pixel amount')
+        .command('scroll')
+        .description('Scroll the page by pixel amount (negatives scroll up/left)')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('--dx <n>', 'Horizontal pixels (negative = left)', (v) => parseInt(v, 10), 0)
+        .option('--dy <n>', 'Vertical pixels (negative = up)', (v) => parseInt(v, 10), 0)
         .option('-x, --at-x <x>', 'X coordinate to dispatch scroll from (default 0)', parseInt)
         .option('-y, --at-y <y>', 'Y coordinate to dispatch scroll from (default 0)', parseInt)
-        .action(async (task, deltaX, deltaY, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
+        if (!Number.isFinite(opts.dx) || !Number.isFinite(opts.dy)) {
+            console.error('--dx and --dy must be integers');
+            process.exit(1);
+        }
+        if (opts.dx === 0 && opts.dy === 0) {
+            console.error('Pass --dx and/or --dy (at least one must be non-zero)');
+            process.exit(1);
+        }
         const response = await sendIPCRequest({
             action: 'scroll',
             task,
             tabId: opts.tab,
-            scrollX: parseInt(deltaX, 10),
-            scrollY: parseInt(deltaY, 10),
+            scrollX: opts.dx,
+            scrollY: opts.dy,
             scrollAtX: opts.atX,
             scrollAtY: opts.atY,
         });
@@ -872,8 +1133,9 @@ function registerTaskCommands(browser) {
         console.log('Scrolled');
     });
     browser
-        .command('upload <task>')
+        .command('upload')
         .description('Upload file(s) — supports hidden file inputs, drag-drop targets, and OS chooser interception')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-r, --ref <n>', 'Ref of the upload target element (file input or drop zone)', (v) => parseInt(v, 10))
         .option('--trigger <n>', 'Ref of a button that opens the OS file chooser (Pattern C)', (v) => parseInt(v, 10))
@@ -881,7 +1143,8 @@ function registerTaskCommands(browser) {
         .option('--drop', 'Force drag-drop pattern even if ref is an <input type=file>')
         .option('--input', 'Force file-input pattern (DOM.setFileInputFiles)')
         .option('--timeout <ms>', 'Timeout for chooser interception (Pattern C)', (v) => parseInt(v, 10))
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const files = opts.file ?? [];
         if (files.length === 0) {
             console.error('--file <path> is required (repeat for multiple files)');
@@ -921,12 +1184,14 @@ function registerTaskCommands(browser) {
     // ─── Viewport & Device ───────────────────────────────────────────────────────
     const setCmd = browser.command('set').description('Set browser emulation options');
     setCmd
-        .command('viewport <task> <width> <height>')
+        .command('viewport <width> <height>')
         .description('Set viewport size')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-m, --mobile', 'Enable mobile emulation')
         .option('-s, --scale <factor>', 'Device scale factor', parseFloat)
-        .action(async (task, width, height, opts) => {
+        .action(async (width, height, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'set-viewport',
             task,
@@ -943,10 +1208,12 @@ function registerTaskCommands(browser) {
         console.log(`Viewport set to ${width}x${height}${opts.mobile ? ' (mobile)' : ''}`);
     });
     setCmd
-        .command('device <task> <device-name>')
+        .command('device <device-name>')
         .description('Emulate a device (iPhone 14, iPad, MacBook Pro)')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .action(async (task, deviceName, opts) => {
+        .action(async (deviceName, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'set-device',
             task,
@@ -971,12 +1238,14 @@ function registerTaskCommands(browser) {
     });
     // ─── Console & Errors ────────────────────────────────────────────────────────
     browser
-        .command('console <task>')
+        .command('console')
         .description('Read console logs from a tab')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-l, --level <level>', 'Filter by level (log, info, warn, error)')
         .option('--clear', 'Clear logs after reading')
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'console',
             task,
@@ -999,11 +1268,13 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('errors <task>')
+        .command('errors')
         .description('Read page errors from a tab')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--clear', 'Clear errors after reading')
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'errors',
             task,
@@ -1029,12 +1300,14 @@ function registerTaskCommands(browser) {
     });
     // ─── Network ─────────────────────────────────────────────────────────────────
     browser
-        .command('requests <task>')
+        .command('requests')
         .description('Read captured network requests')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-f, --filter <text>', 'Filter URLs containing text')
         .option('--clear', 'Clear requests after reading')
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'requests',
             task,
@@ -1058,12 +1331,50 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('responsebody <task> <url-pattern>')
+        .command('logs <task>')
+        .description('Read merged rush-app + rush-cli JSONL logs for a task')
+        .option('--source <name>', 'Source to scope to: rush-app or rush-cli (default both)')
+        .option('--lines <n>', 'Tail N entries (default 200; ignored when --since)', (v) => parseInt(v, 10))
+        .option('--since <when>', 'Absolute timestamp or relative offset (e.g. 5m, 2h, 1d)')
+        .option('--until <when>', 'Absolute timestamp or relative offset (e.g. 5m, 2h, 1d)')
+        .option('--level <level>', 'Filter entries by level field')
+        .option('--message <name>', 'Filter entries by exact message field')
+        .option('--filter <text>', 'Filter entries whose JSON contains this substring')
+        .option('-f, --follow', 'Follow mode (not yet implemented)')
+        .action(async (task, opts) => {
+        if (opts.follow) {
+            process.stderr.write('follow mode not yet implemented; coming next pass\n');
+            process.exit(1);
+        }
+        const response = await sendIPCRequest({
+            action: 'getAppLogs',
+            task,
+            source: opts.source,
+            lines: opts.lines,
+            since: opts.since,
+            until: opts.until,
+            appLevel: opts.level,
+            message: opts.message,
+            filter: opts.filter,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        const entries = response.appLogs ?? [];
+        for (const entry of entries) {
+            console.log(JSON.stringify(entry));
+        }
+    });
+    browser
+        .command('responsebody <url-pattern>')
         .description('Wait for and read a response body by URL pattern')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--timeout <ms>', 'Timeout in milliseconds', parseInt)
         .option('--max-chars <n>', 'Max characters to return', parseInt)
-        .action(async (task, urlPattern, opts) => {
+        .action(async (urlPattern, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'response-body',
             task,
@@ -1080,8 +1391,9 @@ function registerTaskCommands(browser) {
     });
     // ─── Wait ────────────────────────────────────────────────────────────────────
     browser
-        .command('wait <task>')
+        .command('wait')
         .description('Wait for a condition')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--time <ms>', 'Wait for milliseconds')
         .option('--selector <css>', 'Wait for CSS selector to appear')
@@ -1089,7 +1401,8 @@ function registerTaskCommands(browser) {
         .option('--fn <js>', 'Wait for JS expression to return truthy')
         .option('--state <state>', 'Wait for load state (domcontentloaded, load, networkidle)')
         .option('--timeout <ms>', 'Timeout in milliseconds', parseInt)
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         let waitType;
         let waitValue;
         if (opts.time) {
@@ -1132,11 +1445,13 @@ function registerTaskCommands(browser) {
     });
     // ─── Downloads ───────────────────────────────────────────────────────────────
     browser
-        .command('download <task>')
+        .command('download')
         .description('Set download directory for a task')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .requiredOption('-p, --path <dir>', 'Download directory path')
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'set-download-path',
             task,
@@ -1149,11 +1464,58 @@ function registerTaskCommands(browser) {
         }
         console.log(`Download path set to ${opts.path}`);
     });
+    // ─── Recording ─────────────────────────────────────────────────────────────
+    const record = browser.command('record').description('Record a video of the page');
+    record
+        .command('start')
+        .description('Start recording — auto-saved under sessions/<task>/recordings/. Bounded by --fps, --duration, --max-mb.')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('--fps <n>', 'Frames per second (1–30, default 5)', (v) => parseInt(v, 10))
+        .option('--duration <sec>', 'Hard duration cap in seconds (default 60)', (v) => parseInt(v, 10))
+        .option('--max-mb <mb>', 'Stop when output exceeds this many MB (default 25)', (v) => parseInt(v, 10))
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
+        const response = await sendIPCRequest({
+            action: 'record-start',
+            task,
+            tabId: opts.tab,
+            fps: opts.fps,
+            duration: opts.duration,
+            maxMb: opts.maxMb,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        // stdout: path (for capture into a variable). stderr: human commentary.
+        console.log(response.path);
+        console.error(`Recording task "${task}" at ${response.fps} fps (cap ${response.durationCapSec}s / ${response.maxMb} MB) → ${response.path}`);
+        console.error('Stop with: agents browser record stop');
+    });
+    record
+        .command('stop')
+        .description('Stop an in-progress recording')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
+        const response = await sendIPCRequest({ action: 'record-stop', task });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(response.path);
+        const size = humanizeBytes(response.bytes);
+        const seconds = ((response.durationMs ?? 0) / 1000).toFixed(1);
+        console.error(`Saved recording to ${response.path} (${size}, ${seconds}s, stopped: ${response.stopReason})`);
+    });
     browser
-        .command('waitdownload <task>')
+        .command('waitdownload')
         .description('Wait for a download to complete')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('--timeout <ms>', 'Timeout in milliseconds', parseInt)
-        .action(async (task, opts) => {
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'wait-download',
             task,
@@ -1180,6 +1542,15 @@ function formatAge(timestamp) {
     const hours = Math.floor(minutes / 60);
     return `${hours}h ago`;
 }
+function humanizeBytes(n) {
+    if (n === undefined)
+        return 'unknown size';
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(0)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
 function formatDuration(ms) {
     const seconds = Math.floor(ms / 1000);
     if (seconds < 60)