@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/commands/browser.js

@@ -1,13 +1,13 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getConfiguredDefaultProfileName, DEFAULT_BROWSER_PROFILE_NAME, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getConfiguredDefaultProfileName, DEFAULT_BROWSER_PROFILE_NAME, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, listProfilesWithScope, formatProfilesTable, } from '../lib/browser/profiles.js';
 import { resolveActor } from '../lib/actor.js';
 import { loginsForProfile, profilesLoggedInto, serviceForUrl, loginsWithAccountsForProfile, accountsForProfile, credKeysForService, AUTH_SIGNATURES, } from '../lib/browser/login-detection.js';
 import { parseSecretRef } from '../lib/browser/secret-ref.js';
 import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } from '../lib/secrets/bundles.js';
-import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
-import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
+import { findBrowserPath, getPortOccupant, isLauncherScript, listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, buildProfilePrunePlan, pruneProfiles, PRUNE_REASON_TEXT, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
@@ -24,10 +24,13 @@ import { runBrowserIPCStream } from '../lib/browser/stream.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)
+ *   2. `$AGENTS_BROWSER_TASK` (optional shell default)
+ *   3. `undefined` — the daemon resolves from the caller's identity
+ *      (session / launch id stamped in sendIPCRequest)
  *
- * 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.
+ * `undefined` is valid: page verbs create a task when none resolves, and
+ * done/stop report "nothing to close". Agents no longer need to type a handle
+ * in the common case.
  */
 function resolveTaskName(opts) {
     if (opts.task)
@@ -35,20 +38,18 @@ function resolveTaskName(opts) {
     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);
+    return undefined;
 }
 // `-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.
+// The daemon resolves from caller identity when omitted.
 const TASK_OPTION_FLAG = '--task <name>';
-const TASK_OPTION_DESC = 'Task name (defaults to $AGENTS_BROWSER_TASK)';
+const TASK_OPTION_DESC = 'Task name (defaults to $AGENTS_BROWSER_TASK, else the caller\'s live 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: 'Session lifecycle', names: ['use', 'start', 'done', 'status', 'gc'] },
     { title: 'Fast action loop', names: ['stream'] },
     {
         title: 'Drive the page',
@@ -78,7 +79,7 @@ export function registerBrowserCommand(program) {
       # Or pin to a specific profile
       agents browser start --profile work
 
-      # Drive the page
+      # Drive the page (no start / --task needed — identity resolves the task)
       agents browser navigate https://example.com
       agents browser screenshot
 
@@ -86,7 +87,7 @@ export function registerBrowserCommand(program) {
       agents browser stream --task "$AGENTS_BROWSER_TASK"
 
       # Drive another machine's browser (needs its consent — see remote-control)
-      agents browser start --host zion
+      agents browser start --device zion
 
       # Browse a task-heavy profile's captures: one row per task, not per file
       agents browser sessions
@@ -96,27 +97,112 @@ export function registerBrowserCommand(program) {
 
       # End the session when done
       agents browser done
+
+      # Close tabs the daemon's own reaper would have caught on its next 5-min tick
+      agents browser gc --dry-run
     `,
         notes: `
       Most agent workflows should use the 'browser' skill instead of raw subcommands.
       The skill wraps profile selection, snapshotting, and tunneling.
 
-      Browser support: Chromium-family only (Chrome, Comet, Chromium, Brave, Edge).
+      Browser support: Chromium-family only (Chrome, Comet, Chromium, Brave, Edge, Arc).
       Safari and Firefox are not supported — they don't speak the Chrome DevTools
       Protocol the way agents browser expects. On Windows, Edge is the default
       because it's preinstalled. On macOS and Linux, Chrome is preferred when
       installed; otherwise the first Chromium-family binary on disk wins.
     `,
     });
+    registerBrowserUseCommand(browser);
     registerProfilesCommands(browser);
     registerTaskCommands(browser);
     registerCommandGroups(browser, BROWSER_HELP_GROUPS);
 }
 export function registerBrowserSubcommands(program) {
+    registerBrowserUseCommand(program);
     registerProfilesCommands(program);
     registerTaskCommands(program);
     registerCommandGroups(program, BROWSER_HELP_GROUPS);
 }
+export function buildBrowserUseChoices(profiles, installed, current) {
+    const choices = profiles.map((profile) => ({
+        name: `${profile.name}${profile.name === current ? ' (current)' : ''}`,
+        value: { name: profile.name },
+    }));
+    const known = new Set(profiles.map((profile) => profile.name));
+    for (const browser of installed) {
+        const name = `${browser.browserType}-local`;
+        if (!known.has(name)) {
+            choices.push({ name: `${name} (installed ${browser.browserType})`, value: { name, installed: browser } });
+        }
+    }
+    return choices;
+}
+export async function runBrowserUse(name, opts, interactive = isInteractiveTerminal()) {
+    if (opts.unset || name === 'auto') {
+        unsetConfigValue('browser.profile');
+        console.log('Default browser profile cleared. `agents browser start` will auto-detect an installed Chromium-family browser.');
+        return true;
+    }
+    let selectedName = name;
+    if (!selectedName) {
+        const current = getConfiguredDefaultProfileName();
+        if (!interactive) {
+            console.log(current
+                ? `Default browser profile (this machine): ${current}`
+                : 'Default browser profile (this machine): auto-detect');
+            console.log('Usage: agents browser use <name>  (or --unset)');
+            return true;
+        }
+        const choices = buildBrowserUseChoices(await listProfiles(), listInstalledBrowsers(), current);
+        if (choices.length === 0) {
+            console.error('No configured profiles or supported installed browsers found.');
+            console.error('Create one with: agents browser profiles create <name> --browser chrome');
+            return false;
+        }
+        const { select } = await import('@inquirer/prompts');
+        const selected = await select({ message: 'Select default browser profile:', choices });
+        selectedName = selected.name;
+        if (selected.installed) {
+            const freePort = await findFreeProfilePort();
+            await createProfile({
+                name: selected.name,
+                description: `Seeded ${selected.installed.browserType} profile`,
+                browser: selected.installed.browserType,
+                binary: selected.installed.binary,
+                endpoints: [`cdp://127.0.0.1:${freePort}`],
+                viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
+            });
+        }
+    }
+    const target = await getProfile(selectedName);
+    if (!target) {
+        console.error(`Profile "${selectedName}" not found.`);
+        const all = await listProfiles();
+        if (all.length > 0)
+            console.error(`Available profiles: ${all.map((profile) => profile.name).join(', ')}`);
+        return false;
+    }
+    setConfigValue('browser.profile', selectedName);
+    const endpoint = Object.values(getEndpointPresets(target))[0]?.target ?? '';
+    console.log(`Default browser profile (this machine) is now "${selectedName}" (${target.browser}${endpoint ? `, ${endpoint}` : ''}).`);
+    console.log('Bare `agents browser start` and `--profile default` will use it.');
+    return true;
+}
+function configureBrowserUseCommand(command, deprecated = false) {
+    command
+        .description('Pick the profile `agents browser start` uses when no --profile is passed. No name opens a picker on a TTY or prints the current default headlessly.')
+        .option('--unset', 'Clear the configured default (revert to auto-detecting an installed browser)')
+        .action(async (name, opts) => {
+        if (deprecated) {
+            console.warn(chalk.yellow('Deprecation: `agents browser profiles set-default` is replaced by `agents browser use`.'));
+        }
+        if (!await runBrowserUse(name, opts))
+            process.exitCode = 1;
+    });
+}
+function registerBrowserUseCommand(browser) {
+    configureBrowserUseCommand(browser.command('use [name]'));
+}
 /**
  * Whether a profile's secrets bundle holds login creds for `service`
  * (`<PREFIX>_USERNAME` + `<PREFIX>_PASSWORD`). Reads bundle METADATA only (key
@@ -147,84 +233,59 @@ function registerProfilesCommands(browser) {
     profiles
         .command('list')
         .alias('ls')
-        .description('List all browser profiles')
-        .action(async () => {
-        const allProfiles = await listProfiles();
-        if (allProfiles.length === 0) {
-            console.log('No browser profiles configured.');
-            console.log('Create one with: agents browser profiles create <name> --endpoint <url>');
-            return;
-        }
-        // The configured default is what a bare `agents browser start` (and an
-        // explicit `--profile default`) resolves to on THIS machine — mark it.
+        .description('List all browser profiles, with the store each lives in (local / fleet)')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (opts) => {
+        const scoped = await listProfilesWithScope();
         const configuredDefault = getConfiguredDefaultProfileName();
-        const marker = (name) => (name === configuredDefault ? '   (default)' : '');
-        const hasDescriptions = allProfiles.some(p => p.description);
-        if (hasDescriptions) {
-            console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'DESCRIPTION'.padEnd(38) + 'ENDPOINTS');
-            console.log('-'.repeat(92));
-            for (const p of allProfiles) {
-                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 + marker(p.name));
-            }
-        }
-        else {
-            console.log('NAME'.padEnd(20) + 'BROWSER'.padEnd(12) + 'ENDPOINTS');
-            console.log('-'.repeat(72));
-            for (const p of allProfiles) {
-                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 + marker(p.name));
-            }
+        if (opts.json) {
+            console.log(JSON.stringify(scoped.map(({ profile, scope }) => ({
+                ...profile,
+                scope,
+                isConfiguredDefault: profile.name === configuredDefault,
+            })), null, 2));
+            return;
         }
-        if (configuredDefault) {
-            console.log('');
-            console.log(`Default profile (this machine): ${configuredDefault}`);
+        if (scoped.length === 0) {
+            console.log('No browser profiles configured.');
+            console.log('Create one with: agents browser profiles create <name> --browser chrome');
+            return;
         }
+        // Rendering lives in lib/browser/profiles.ts so the column widths and the
+        // default-marking rules are unit-tested rather than eyeballed (RUSH-2710).
+        for (const line of formatProfilesTable(scoped, configuredDefault))
+            console.log(line);
     });
-    const browserProfileDeprecation = chalk.yellow('Deprecation: `agents browser profiles set-default` is replaced by `agents config set browser.profile <name>`.');
     profiles
-        .command('set-default [name]')
-        .description('Set the profile `agents browser start` uses when no --profile is passed (also re-points an explicit `--profile default`). Device-local — each machine has its own. No name prints the current value.')
-        .option('--unset', 'Clear the configured default (revert to auto-detecting an installed browser)')
-        .action(async (name, opts) => {
-        console.warn(browserProfileDeprecation);
-        if (opts.unset) {
-            unsetConfigValue('browser.profile');
-            console.log('Default browser profile cleared. `agents browser start` will auto-detect an installed Chromium-family browser.');
-            return;
+        .command('seed')
+        .description('Create a machine-local profile for each installed browser (named <browser>-local), so you can pick or use one instead of hand-crafting each. Idempotent — existing profiles are left untouched.')
+        .action(async () => {
+        const installed = listInstalledBrowsers();
+        if (installed.length === 0) {
+            console.error('No supported browser found to seed a profile for.');
+            process.exit(1);
         }
-        if (!name) {
-            const current = getConfiguredDefaultProfileName();
-            if (current) {
-                console.log(`Default browser profile (this machine): ${current}`);
-            }
-            else {
-                console.log('No default browser profile set. `agents browser start` auto-detects an installed Chromium-family browser.');
-                console.log('Set one with: agents config set browser.profile <name>');
+        for (const { browserType, binary } of installed) {
+            const name = `${browserType}-local`;
+            if (await getProfile(name)) {
+                console.log(`= ${name} (already exists)`);
+                continue;
             }
-            return;
-        }
-        const target = await getProfile(name);
-        if (!target) {
-            console.error(`Profile "${name}" not found.`);
-            const all = await listProfiles();
-            if (all.length > 0)
-                console.error(`Available profiles: ${all.map((p) => p.name).join(', ')}`);
-            process.exit(1);
+            const freePort = await findFreeProfilePort();
+            await createProfile({
+                name,
+                description: `Seeded ${browserType} profile`,
+                browser: browserType,
+                binary,
+                endpoints: [`cdp://127.0.0.1:${freePort}`],
+                viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
+            });
+            console.log(`+ ${name} (${browserType})`);
         }
-        setConfigValue('browser.profile', name);
-        const eps = getEndpointPresets(target);
-        const epStr = Object.values(eps)[0]?.target ?? '';
-        console.log(`Default browser profile (this machine) is now "${name}" (${target.browser}${epStr ? `, ${epStr}` : ''}).`);
-        console.log('Bare `agents browser start` and `--profile default` will use it.');
+        console.log('Pick your default with: agents browser use <name>');
     });
+    configureBrowserUseCommand(profiles.command('use [name]'));
+    configureBrowserUseCommand(profiles.command('set-default [name]', { hidden: true }), true);
     profiles
         .command('logins')
         .description('Show which login-gated services each profile has a live session for, the account signed in, and whether login creds are available in the profile\'s secrets bundle (reads cookie/username presence only, never decrypts).')
@@ -253,11 +314,12 @@ function registerProfilesCommands(browser) {
             }
         }
     });
-    const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge', 'custom'];
+    const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge', 'arc', 'custom'];
     profiles
         .command('create <name>')
-        .description('Create a new browser profile')
+        .description('Create a new browser profile (machine-local unless --fleet)')
         .requiredOption('-b, --browser <type>', `Browser type: ${VALID_BROWSERS.join(', ')}`)
+        .option('--fleet', 'Store in the synced agents.yaml so every machine sees it. Default is machine-local: a profile pins an OS-specific binary path and a locally chosen port, so a synced copy is wrong on every other box.')
         .option('-e, --endpoint <url>', 'CDP endpoint URL (repeatable; auto-assigned if omitted)', collect, [])
         .option('-s, --secrets <bundle>', 'Secrets bundle to inject')
         .option('-d, --description <text>', 'Profile description')
@@ -337,8 +399,8 @@ function registerProfilesCommands(browser) {
             chrome: opts.headless ? { headless: true } : undefined,
             viewport,
         };
-        await createProfile(profile);
-        console.log(`Created profile: ${name}`);
+        await createProfile(profile, { fleet: !!opts.fleet });
+        console.log(`Created profile: ${name} (${opts.fleet ? 'fleet-synced — visible on every machine' : 'machine-local'})`);
         // Warn (don't fail) if the declared secrets bundle doesn't exist yet — it
         // may be created later, but a typo should surface now.
         if (opts.secrets && !bundleExists(opts.secrets)) {
@@ -452,9 +514,76 @@ function registerProfilesCommands(browser) {
             (removed > 0 ? ` (and ${removed} cache dir${removed === 1 ? '' : 's'})` : ''));
         if (getConfiguredDefaultProfileName() === name) {
             console.error(`warning: "${name}" was this machine's default browser profile; ` +
-                `\`agents browser start\` will auto-detect until you run: agents config set browser.profile <name>`);
+                `\`agents browser start\` will auto-detect until you run: agents browser use <name>`);
         }
     });
+    profiles
+        .command('prune')
+        .description('Remove dead machine-local profiles: browser not installed here, or never started')
+        .option('-n, --dry-run', 'Print what would be removed and exit without changing anything')
+        .option('--fleet', 'Also consider fleet-synced profiles (removing one removes it from EVERY machine)')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (opts) => {
+        const plan = await buildProfilePrunePlan({ includeFleet: opts.fleet });
+        if (!opts.dryRun)
+            await pruneProfiles(plan);
+        if (opts.json) {
+            console.log(JSON.stringify({ dryRun: !!opts.dryRun, ...plan }, null, 2));
+            return;
+        }
+        if (plan.candidates.length === 0) {
+            console.log('Nothing to prune — every profile is in use, healthy, or protected.');
+            if (plan.kept.length > 0) {
+                for (const k of plan.kept)
+                    console.log(`  kept ${k.name} (${k.scope}) — ${k.why}`);
+            }
+            return;
+        }
+        const verb = opts.dryRun ? 'Would remove' : 'Removed';
+        console.log(`${verb} ${plan.candidates.length} profile${plan.candidates.length === 1 ? '' : 's'}:`);
+        for (const c of plan.candidates) {
+            const cache = c.cacheDirs.length > 0
+                ? ` + ${c.cacheDirs.length} cache dir${c.cacheDirs.length === 1 ? '' : 's'}`
+                : '';
+            console.log(`  ${c.name} (${c.scope}) — ${PRUNE_REASON_TEXT[c.reason]}${cache}`);
+        }
+        if (opts.dryRun) {
+            console.log('');
+            console.log('Nothing was changed. Re-run without --dry-run to apply.');
+        }
+    });
+    setHelpSections(profiles, {
+        examples: `
+      # What exists here, and whether each is this machine's or the whole fleet's
+      agents browser profiles list
+
+      # Create one — machine-local by default
+      agents browser profiles create work --browser chrome
+
+      # Create one every machine should see (e.g. a remote ssh:// endpoint)
+      agents browser profiles create shared-remote --browser chrome --fleet
+
+      # Clean up dead ones: check first, then apply
+      agents browser profiles prune --dry-run
+      agents browser profiles prune
+
+      # Make one the machine's default for a bare \`agents browser start\`
+      agents browser use work
+    `,
+        notes: `
+      Profiles are machine-local by default. A profile pins an OS-specific binary
+      path and a locally chosen CDP port, so a fleet-synced copy is wrong on every
+      other machine — pass --fleet only when the profile really is fleet config.
+
+      In \`list\`, the \`*\` marker means "this machine's configured default"
+      (\`agents browser start\` with no --profile). It is NOT the same thing as the
+      profile NAMED \`default\`, which is the auto-detected one; they are often
+      different profiles.
+
+      \`prune\` never removes a profile that is in use, the configured default, the
+      auto \`default\`, or (without --fleet) a fleet-synced one.
+    `,
+    });
     profiles
         .command('doctor <name>')
         .description('Diagnose a browser profile: binary, port, user-data-dir, onboarding state')
@@ -627,7 +756,7 @@ function registerProfilesCommands(browser) {
 function registerTaskCommands(browser) {
     browser
         .command('remote-control [state]')
-        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --host`. " +
+        .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --device`. " +
         '`on`/`off` to set (device-local, never synced); no argument prints the current value. Default off.')
         .option('--json', 'Output as JSON')
         .action((state, opts) => {
@@ -658,8 +787,8 @@ function registerTaskCommands(browser) {
         }
         console.log(`Remote browser control (this machine) is now ${value ? 'on' : 'off'}.`);
         console.log(value
-            ? 'Other fleet machines can now drive this browser via `browser --host <this-device>`.'
-            : 'Cross-machine `browser --host` drives to this machine are refused.');
+            ? 'Other fleet machines can now drive this browser via `browser --device <this-device>`.'
+            : 'Cross-machine `browser --device` drives to this machine are refused.');
     });
     const stream = browser
         .command('stream')
@@ -694,9 +823,10 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('start')
-        .description('Start a browser task. Pass --profile <name>; omit to use your configured default (`agents config set browser.profile <name>`), else auto-pick an installed Chromium-family browser.')
+        .description('Start a browser task. Pass --profile <name>; omit to use your configured default (`agents browser use <name>`), else auto-pick an installed Chromium-family browser. Page verbs (navigate/screenshot/…) create a task implicitly when none exists — start is for --profile/--url/--record/--title.')
         .option('-p, --profile <name>', 'Browser profile to use (omit to use the configured default, else auto-pick an installed Chromium-family browser)')
-        .option(TASK_OPTION_FLAG, 'Task name (auto-generated if omitted)')
+        .option(TASK_OPTION_FLAG, 'Task name (auto-generated short id if omitted)')
+        .option('--title <label>', 'Human label shown in `browser status` (defaults to first navigated host)')
         .option('-e, --endpoint <name>', 'Endpoint preset (defaults to the profile\'s default)')
         .option('-u, --url <url>', 'Open URL in first tab')
         .option('--fresh', 'Always open a new tab, skipping the reclaim of a tab an abandoned task is holding on that URL')
@@ -706,7 +836,7 @@ function registerTaskCommands(browser) {
         .option('--duration <sec>', 'Recording duration cap in seconds (with --record; default 60)', (v) => parseInt(v, 10))
         .option('--max-mb <mb>', 'Recording size cap in MB (with --record; default 25)', (v) => parseInt(v, 10))
         .action(async (opts) => {
-        // Consent gate: a fleet-remote `browser --host <this-machine> start` may
+        // Consent gate: a fleet-remote `browser --device <this-machine> start` may
         // only open a browser here if the owner opted in. Refuse before we resolve
         // or auto-create any profile. Local starts are never gated.
         try {
@@ -753,7 +883,7 @@ function registerTaskCommands(browser) {
             if (all.length > 0) {
                 console.error(`Available profiles: ${all.map((p) => p.name).join(', ')}`);
             }
-            console.error(`Create one with: agents browser profiles create ${profileName} --browser <chrome|comet|chromium|brave|edge|custom>`);
+            console.error(`Create one with: agents browser profiles create ${profileName} --browser <chrome|comet|chromium|brave|edge|arc|custom>`);
             process.exit(1);
         }
         // Pre-check the endpoint name too — same fail-fast rationale.
@@ -785,6 +915,7 @@ function registerTaskCommands(browser) {
             }
             catch { /* login detection is best-effort; never block start */ }
         }
+        // Identity is stamped inside sendIPCRequest; no need to pass it here.
         const response = await sendIPCRequest({
             action: 'start',
             profile: profileName,
@@ -793,17 +924,7 @@ function registerTaskCommands(browser) {
             endpoint: opts.endpoint,
             skipDomainSkill: opts.skills === false,
             fresh: opts.fresh === true,
-            // Forward the caller's identity: the browser daemon is shared, so it
-            // cannot resolve who/which-run called `start`. `resolveActor()` runs
-            // here in the CLI (the caller's process); `$AGENT_LAUNCH_ID` is the
-            // per-run id exec.ts injects for every harness.
-            actor: resolveActor().id,
-            launchId: process.env.AGENT_LAUNCH_ID,
-            // The agent session that drove this task — what makes the capture
-            // traceable back to a conversation (RUSH-2549). Sent alongside, not
-            // instead of, launchId: a launch id is absent on most agent processes,
-            // a session id is not.
-            sessionId: process.env.AGENT_SESSION_ID || process.env.AGENTS_SESSION_ID,
+            title: opts.title,
         });
         if (!response.ok) {
             console.error(response.error);
@@ -820,7 +941,7 @@ function registerTaskCommands(browser) {
         else {
             console.error(`Started task "${response.task}"`);
         }
-        console.error(`Tip: export AGENTS_BROWSER_TASK=${response.task}`);
+        console.error('Tip: page verbs resolve this task from your session — --task only when running two at once.');
         console.error('Try: agents browser screenshot | agents browser console --level error');
         // Surface the matched domain-skill (if any) so an agent driving the
         // task picks up site-specific selectors and gotchas before it starts
@@ -855,7 +976,7 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('done')
-        .description('Complete a task and close its tabs')
+        .description('Complete a task and close its tabs (resolves from caller identity when --task is omitted)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .action(async (opts) => {
         const task = resolveTaskName(opts);
@@ -867,7 +988,11 @@ function registerTaskCommands(browser) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log(`Completed task: ${task}`);
+        if (response.message === 'nothing to close' || !response.task) {
+            console.log('nothing to close');
+            return;
+        }
+        console.log(`Completed task: ${response.task}`);
     });
     browser
         .command('stop')
@@ -896,27 +1021,78 @@ function registerTaskCommands(browser) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log(`Stopped task: ${task}`);
+        if (response.message === 'nothing to close' || !response.task) {
+            console.log('nothing to close');
+            return;
+        }
+        console.log(`Stopped task: ${response.task}`);
     });
     browser
-        .command('navigate')
-        .description('Navigate current tab to URL (creates tab if none exist)')
+        .command('gc')
+        .description('Close tabs for abandoned tasks — owning agent session exited, or idle past the window — and mark them done. ' +
+        'The same reaper the daemon already runs every 5 minutes; use this to run it now.')
+        .option('--dry-run', 'List what would be closed without closing anything')
+        .option('--idle-minutes <n>', 'Override the idle window in minutes (default: this device\'s browser.task-idle-minutes, or 30). ' +
+        '0 disables idle-only closing for this run; session-dead tasks are still closed.', (v) => parseInt(v, 10))
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (opts) => {
+        const response = await sendIPCRequest({
+            action: 'gc',
+            dryRun: opts.dryRun,
+            idleMinutes: opts.idleMinutes,
+        });
+        if (!response.ok) {
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: false, error: response.error }));
+            }
+            else {
+                console.error(response.error);
+            }
+            process.exit(1);
+        }
+        const reaped = response.reaped ?? { closed: [], skipped: 0 };
+        if (opts.json) {
+            console.log(JSON.stringify(reaped, null, 2));
+            return;
+        }
+        if (reaped.closed.length === 0) {
+            console.log(`No abandoned tasks${opts.dryRun ? ' (dry run)' : ''}; ${reaped.skipped} task(s) still active.`);
+            return;
+        }
+        const verb = opts.dryRun ? 'Would close' : 'Closed';
+        console.log(`${verb} ${reaped.closed.length} task(s), left ${reaped.skipped} alone:`);
+        for (const c of reaped.closed) {
+            console.log(`  ${c.task}  (${c.profile}, ${c.reason})`);
+        }
+    });
+    browser
+        .command('navigate [url]')
+        .alias('goto')
+        .description('Navigate current tab to URL (creates a task and tab when none exist)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
-        .requiredOption('--url <url>', 'URL to navigate to')
+        .option('-u, --url <url>', 'URL to navigate to (or pass it positionally)')
         .option('-p, --profile <name>', 'Browser profile (optional if task is unique)')
-        .action(async (opts) => {
+        .action(async (urlPos, opts) => {
+        const url = urlPos || opts.url;
+        if (!url) {
+            console.error('URL required. Usage: agents browser navigate <url>');
+            process.exit(1);
+        }
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'navigate',
             task,
-            url: opts.url,
+            url,
             profile: opts.profile,
         });
         if (!response.ok) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log(`Navigated ${response.tabId} to ${opts.url}`);
+        if (response.task) {
+            console.error(`task ${response.task}`);
+        }
+        console.log(`Navigated ${response.tabId} to ${url}`);
     });
     // Tab subcommand group
     const tab = browser.command('tab').description('Manage tabs');
@@ -1073,16 +1249,18 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('evaluate')
+        .command('evaluate [expression]')
+        .alias('eval')
         .description('Evaluate JavaScript in current tab')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
-        .option('-e, --expression <js>', 'JavaScript expression to evaluate')
+        .option('-e, --expression <js>', 'JavaScript expression to evaluate (or pass it positionally)')
         .option('-f, --file <path>', 'Path to a .js file whose contents will be evaluated')
-        .action(async (opts) => {
+        .action(async (exprPos, opts) => {
         const task = resolveTaskName(opts);
-        if (opts.expression && opts.file) {
-            console.error('Pass exactly one of --expression or --file');
+        const flagExpr = opts.expression || exprPos;
+        if (flagExpr && opts.file) {
+            console.error('Pass exactly one of an expression or --file');
             process.exit(1);
         }
         let expression;
@@ -1095,11 +1273,11 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
         }
-        else if (opts.expression) {
-            expression = opts.expression;
+        else if (flagExpr) {
+            expression = flagExpr;
         }
         else {
-            console.error('Pass --expression <js> or --file <path>');
+            console.error('Pass an expression positionally, -e <js>, or --file <path>');
             process.exit(1);
         }
         const response = await sendIPCRequest({
@@ -1285,15 +1463,22 @@ function registerTaskCommands(browser) {
                     console.log('  No active tasks');
                 }
                 else {
-                    console.log('  TASK'.padEnd(20) + 'TABS'.padEnd(6) + 'DOMAINS'.padEnd(25) + 'CREATED');
+                    console.log('  ' +
+                        'ID'.padEnd(12) +
+                        'LABEL'.padEnd(20) +
+                        'TABS'.padEnd(6) +
+                        'DOMAINS'.padEnd(22) +
+                        'CREATED');
                     for (const task of profile.tasks) {
                         const age = formatAge(task.createdAt);
-                        const name = task.name || task.id;
+                        const id = (task.name || task.id).slice(0, 10);
+                        const label = (task.label || task.name || task.id).slice(0, 18);
                         const domains = task.domains?.slice(0, 2).join(', ') || '-';
                         console.log('  ' +
-                            name.padEnd(18) +
+                            id.padEnd(12) +
+                            label.padEnd(20) +
                             String(task.tabCount).padEnd(6) +
-                            domains.slice(0, 23).padEnd(25) +
+                            domains.slice(0, 20).padEnd(22) +
                             age);
                     }
                 }
@@ -1842,8 +2027,9 @@ function registerTaskCommands(browser) {
         }
     });
     browser
-        .command('logs <task>')
+        .command('logs')
         .description('Read merged rush-app + rush-cli JSONL logs for a task')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .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)')
@@ -1852,11 +2038,12 @@ function registerTaskCommands(browser) {
         .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) => {
+        .action(async (opts) => {
         if (opts.follow) {
             process.stderr.write('follow mode not yet implemented; coming next pass\n');
             process.exit(1);
         }
+        const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
             action: 'getAppLogs',
             task,