@phnx-labs/agents-cli 1.22.39 → 1.22.40

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 { 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: ['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,6 +97,9 @@ 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.
@@ -147,46 +151,28 @@ 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
@@ -256,8 +242,9 @@ function registerProfilesCommands(browser) {
     const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge', '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 +324,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)) {
@@ -455,6 +442,73 @@ function registerProfilesCommands(browser) {
                 `\`agents browser start\` will auto-detect until you run: agents config set browser.profile <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 config set browser.profile 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 +681,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 +712,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 +748,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 config set browser.profile <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 +761,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 {
@@ -785,6 +840,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 +849,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 +866,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 +901,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 +913,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 +946,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('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')
-        .description('Navigate current tab to URL (creates tab if none exist)')
+        .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 +1174,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 +1198,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 +1388,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 +1952,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 +1963,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,

package/dist/commands/budget.d.ts

@@ -1,14 +1,15 @@
 /**
- * `agents budget` — view and set spend caps (issue #346).
+ * `agents config budget` — view and set spend caps (issue #346).
  *
- *   agents budget                show effective caps + spend-to-cap (today + project)
- *   agents budget --json         machine-readable snapshot
- *   agents budget set <cap> <n>  write a cap to the user agents.yaml budget: block
+ *   agents config budget                show effective caps + spend-to-cap (today + project)
+ *   agents config budget --json         machine-readable snapshot
+ *   agents config budget set <cap> <n>  write a cap to the user agents.yaml budget: block
  *
- * Caps resolve project > user (see lib/budget/config.ts); `agents budget`
+ * Caps resolve project > user (see lib/budget/config.ts); `agents config budget`
  * reports the EFFECTIVE merged config for the current directory, and `set`
  * writes the user-global layer (the project layer is hand-edited in the repo's
  * agents.yaml, like every other project override).
  */
 import type { Command } from 'commander';
-export declare function registerBudgetCommand(program: Command): void;
+/** Register `agents config budget` under the config parent. */
+export declare function registerBudgetCommand(configCmd: Command): void;

package/dist/commands/budget.js

@@ -5,8 +5,9 @@ import { resolveBudgetConfig, hasAnyCap } from '../lib/budget/config.js';
 import { loadLedger, spendForDay, spendForProject, spendForAgentDay, localDay } from '../lib/budget/ledger.js';
 import { formatUsd } from '../lib/pricing/index.js';
 const TOP_CAPS = ['per_run', 'per_day', 'per_project'];
-export function registerBudgetCommand(program) {
-    const budgetCmd = program
+/** Register `agents config budget` under the config parent. */
+export function registerBudgetCommand(configCmd) {
+    const budgetCmd = configCmd
         .command('budget')
         .description('Show spend caps and current spend-to-cap (issue #346)')
         .option('--json', 'Emit the budget + spend snapshot as JSON')
@@ -52,10 +53,10 @@ export function registerBudgetCommand(program) {
         .description(`Set a user-global cap. <cap> = ${TOP_CAPS.join(' | ')} | per_agent.<agent> | on_exceed | require_confirm_over`)
         .addHelpText('after', `
 Examples:
-  agents budget set per_run 5            Cap any single run at $5
-  agents budget set per_day 50           Cap total spend per day at $50
-  agents budget set per_agent.claude 30  Cap Claude's daily spend at $30
-  agents budget set on_exceed warn       Switch to warn-only (do not block)
+  agents config budget set per_run 5            Cap any single run at $5
+  agents config budget set per_day 50           Cap total spend per day at $50
+  agents config budget set per_agent.claude 30  Cap Claude's daily spend at $30
+  agents config budget set on_exceed warn       Switch to warn-only (do not block)
 `)
         .action((cap, amount) => {
         const meta = readMeta();
@@ -116,7 +117,7 @@ function renderBudget(cfg, snap) {
     lines.push(chalk.dim(`  day:     ${snap.day}`));
     lines.push('');
     if (!hasAnyCap(cfg)) {
-        lines.push(chalk.dim('  No caps configured. Set one with: agents budget set per_run 5'));
+        lines.push(chalk.dim('  No caps configured. Set one with: agents config budget set per_run 5'));
         return lines.join('\n');
     }
     lines.push(capLine('per_run', null, cfg.per_run));