@phnx-labs/agents-cli 1.18.4 → 1.18.6

package/dist/commands/browser.js

@@ -1,17 +1,8 @@
-import { Argument } from 'commander';
-// Hidden trailing positional we use to capture the deprecated `<task>` slot
-// without polluting `--help`. Required for backward compat during migration.
-// commander v12 Argument lacks `hideHelp()`; we set the field our custom
-// help formatter (src/lib/help.ts) already filters on.
-function hiddenLegacyArg(name = 'legacyArg') {
-    const arg = new Argument(`[${name}]`, 'deprecated — legacy task positional');
-    arg.hidden = true;
-    return arg;
-}
 import * as fs from 'fs';
 import * as path from 'path';
 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';
@@ -22,27 +13,14 @@ import { registerCommandGroups } from '../lib/help.js';
 /**
  * Resolve which browser task a command targets. Order:
  *   1. `--task <name>` flag (explicit per-command override)
- *   2. Legacy positional `<task>` arg (deprecated; emits a one-time warning)
- *   3. `$AGENTS_BROWSER_TASK` (set once at the start of an agent run)
+ *   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.
  */
-let legacyTaskWarned = false;
-function warnLegacyTaskPositional() {
-    if (legacyTaskWarned)
-        return;
-    legacyTaskWarned = true;
-    console.error('warning: passing <task> as a positional argument is deprecated. ' +
-        'Set AGENTS_BROWSER_TASK once per shell, or use --task <name> for a one-off override.');
-}
-function resolveTaskName(opts, legacyTaskArg) {
+function resolveTaskName(opts) {
     if (opts.task)
         return opts.task;
-    if (legacyTaskArg !== undefined && legacyTaskArg !== '') {
-        warnLegacyTaskPositional();
-        return legacyTaskArg;
-    }
     const fromEnv = process.env.AGENTS_BROWSER_TASK;
     if (fromEnv)
         return fromEnv;
@@ -50,21 +28,6 @@ function resolveTaskName(opts, legacyTaskArg) {
     console.error('Tip: T=$(agents browser start --profile <p>) && export AGENTS_BROWSER_TASK=$T');
     process.exit(1);
 }
-/**
- * Split positional args into (deprecated leading task, new-shape positionals).
- *
- * If exactly one more positional than the new shape expects is supplied, treat
- * the first one as the deprecated `<task>` positional and shift the rest. Used
- * to keep old `agents browser navigate <task> <url>` style invocations working
- * during the migration to `--task <name>` / `$AGENTS_BROWSER_TASK`.
- */
-function unpackPositionals(rawArgs, newPositionalCount, opts) {
-    const defined = rawArgs.filter((a) => a !== undefined);
-    if (defined.length === newPositionalCount + 1) {
-        return { task: resolveTaskName(opts, defined[0]), positionals: defined.slice(1) };
-    }
-    return { task: resolveTaskName(opts), positionals: defined };
-}
 // `-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>';
@@ -81,7 +44,7 @@ const BROWSER_HELP_GROUPS = [
     },
     {
         title: 'Capture evidence',
-        names: ['console', 'errors', 'requests', 'responsebody', 'record'],
+        names: ['console', 'errors', 'requests', 'responsebody', 'record', 'logs'],
     },
 ];
 export function registerBrowserCommand(program) {
@@ -279,10 +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}`);
+        // 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);
+        }
+        console.log(`Deleted profile: ${name}` +
+            (removed > 0 ? ` (and ${removed} cache dir${removed === 1 ? '' : 's'})` : ''));
     });
     profiles
         .command('doctor <name>')
@@ -306,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) {
@@ -464,11 +468,10 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('done')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .description('Complete a task and close its tabs')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
-        .action(async (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'done',
             task,
@@ -481,11 +484,23 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('stop')
-        .addArgument(hiddenLegacyArg('legacyTask'))
-        .description('Stop a browser task and close its tabs')
+        .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)
-        .action(async (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .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,
@@ -497,57 +512,53 @@ function registerTaskCommands(browser) {
         console.log(`Stopped task: ${task}`);
     });
     browser
-        .command('navigate <url>')
-        .addArgument(hiddenLegacyArg('legacyUrl'))
+        .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [url] = positionals;
+        .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 <url>')
-        .addArgument(hiddenLegacyArg('legacyUrl'))
+        .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [url] = positionals;
+        .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 <tabId>')
-        .addArgument(hiddenLegacyArg('legacyTabId'))
         .description('Switch to tab (by ID, prefix, or URL substring)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
-        .action(async (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [tabId] = positionals;
+        .action(async (tabId, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'tab-focus',
             task,
@@ -612,12 +623,13 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('screenshot [tabId]')
+        .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 (tabId, opts) => {
+        .action(async (opts) => {
         const task = resolveTaskName(opts);
         if (opts.quality !== 'compressed' && opts.quality !== 'raw') {
             console.error('--quality must be "compressed" or "raw"');
@@ -626,7 +638,7 @@ function registerTaskCommands(browser) {
         const response = await sendIPCRequest({
             action: 'screenshot',
             task,
-            tabId,
+            tabId: opts.tab,
             path: opts.output,
             quality: opts.quality,
         });
@@ -641,16 +653,43 @@ function registerTaskCommands(browser) {
         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 <expression>')
-        .addArgument(hiddenLegacyArg('legacyExpression'))
+        .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [expression] = positionals;
+        .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,
@@ -663,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')
@@ -877,15 +983,14 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('refs')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'refs',
             task,
@@ -910,13 +1015,11 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('click <ref>')
-        .addArgument(hiddenLegacyArg('legacyRef'))
         .description('Click an element by ref')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .action(async (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [ref] = positionals;
+        .action(async (ref, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'click',
             task,
@@ -930,21 +1033,25 @@ function registerTaskCommands(browser) {
         console.log('Clicked');
     });
     browser
-        .command('type <ref> <text>')
-        .addArgument(hiddenLegacyArg('legacyText'))
+        .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 (arg1, arg2, arg3, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2, arg3], 2, opts);
-        const [ref, text] = positionals;
+        .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) {
@@ -955,13 +1062,11 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('press <key>')
-        .addArgument(hiddenLegacyArg('legacyKey'))
         .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [key] = positionals;
+        .action(async (key, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'press',
             task,
@@ -976,13 +1081,11 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('hover <ref>')
-        .addArgument(hiddenLegacyArg('legacyRef'))
         .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [ref] = positionals;
+        .action(async (ref, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'hover',
             task,
@@ -996,22 +1099,30 @@ function registerTaskCommands(browser) {
         console.log('Hovered');
     });
     browser
-        .command('scroll <deltaX> <deltaY>')
-        .addArgument(hiddenLegacyArg('legacyDeltaY'))
-        .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 (arg1, arg2, arg3, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2, arg3], 2, opts);
-        const [deltaX, deltaY] = positionals;
+        .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,
         });
@@ -1023,7 +1134,6 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('upload')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .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)')
@@ -1033,8 +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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, 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)');
@@ -1075,15 +1185,13 @@ function registerTaskCommands(browser) {
     const setCmd = browser.command('set').description('Set browser emulation options');
     setCmd
         .command('viewport <width> <height>')
-        .addArgument(hiddenLegacyArg('legacyHeight'))
         .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 (arg1, arg2, arg3, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2, arg3], 2, opts);
-        const [width, height] = positionals;
+        .action(async (width, height, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'set-viewport',
             task,
@@ -1101,13 +1209,11 @@ function registerTaskCommands(browser) {
     });
     setCmd
         .command('device <device-name>')
-        .addArgument(hiddenLegacyArg('legacyDeviceName'))
         .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [deviceName] = positionals;
+        .action(async (deviceName, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'set-device',
             task,
@@ -1133,14 +1239,13 @@ function registerTaskCommands(browser) {
     // ─── Console & Errors ────────────────────────────────────────────────────────
     browser
         .command('console')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'console',
             task,
@@ -1164,13 +1269,12 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('errors')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'errors',
             task,
@@ -1197,14 +1301,13 @@ function registerTaskCommands(browser) {
     // ─── Network ─────────────────────────────────────────────────────────────────
     browser
         .command('requests')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'requests',
             task,
@@ -1227,17 +1330,51 @@ function registerTaskCommands(browser) {
             console.log(`${req.method.padEnd(8)}${status.padEnd(8)}${req.url.slice(0, 100)}`);
         }
     });
+    browser
+        .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>')
-        .addArgument(hiddenLegacyArg('legacyUrlPattern'))
         .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 (arg1, arg2, opts) => {
-        const { task, positionals } = unpackPositionals([arg1, arg2], 1, opts);
-        const [urlPattern] = positionals;
+        .action(async (urlPattern, opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'response-body',
             task,
@@ -1255,7 +1392,6 @@ function registerTaskCommands(browser) {
     // ─── Wait ────────────────────────────────────────────────────────────────────
     browser
         .command('wait')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .description('Wait for a condition')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
@@ -1265,8 +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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         let waitType;
         let waitValue;
         if (opts.time) {
@@ -1310,13 +1446,12 @@ function registerTaskCommands(browser) {
     // ─── Downloads ───────────────────────────────────────────────────────────────
     browser
         .command('download')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .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 (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'set-download-path',
             task,
@@ -1376,12 +1511,11 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('waitdownload')
-        .addArgument(hiddenLegacyArg('legacyTask'))
         .description('Wait for a download to complete')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('--timeout <ms>', 'Timeout in milliseconds', parseInt)
-        .action(async (legacyTask, opts) => {
-        const { task } = unpackPositionals([legacyTask], 0, opts);
+        .action(async (opts) => {
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'wait-download',
             task,