@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/commands/browser.js

@@ -1,55 +1,259 @@
 import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
 import * as fs from 'fs';
 import * as path from 'path';
-import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, listProfilesWithScope, formatProfilesTable, } from '../lib/browser/profiles.js';
+import { listProfiles, getProfile, createProfile, deleteProfile, getConfiguredDefaultProfileName, resolveProfileRef, resolveProfileRefForStart, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, formatProfilesTable, editProfile, renameProfile, assertRegistrableProfileName, isProfileLaunchableHere, } from '../lib/browser/profiles.js';
+import { declaringDevices, migrateCentralBrowserProfiles, profileKind } from '../lib/browser/registry.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, 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 { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, buildProfilePrunePlan, pruneProfiles, PRUNE_REASON_TEXT, identityLoopbackMismatch, } from '../lib/browser/runtime-state.js';
+import { DEFAULT_VIEWPORT, parseWindowSize, parseWindowPosition } from '../lib/browser/devices.js';
 import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
-import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest, } from '../lib/browser/ipc.js';
+import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest as sendRawIPCRequest, } from '../lib/browser/ipc.js';
+import { bindTask, getTaskBinding, honorScreenshotOutput, REJECT_DEVICE_MESSAGE, resolveTaskRoute, unbindTask, unbindTasksForProfile, updateTaskBinding, } from '../lib/browser/task-index.js';
+import { isSelfHost } from '../lib/devices/self-host.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
+import { withActorEnv } from '../lib/hosts/dispatch.js';
+import { streamAgentsOnHost, passthroughSshOptions, } from '../lib/hosts/passthrough.js';
+import { buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, stripRoutingFlags, } from '../lib/hosts/remote-cmd.js';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { sshExec, SSH_OPTS } from '../lib/ssh-exec.js';
+import { flagValue } from '../lib/hosts/routing-flag.js';
 import { browserTaskPicker } from './browser-picker.js';
-import { assertRemoteControlAllowed } from '../lib/browser/remote-control.js';
+import { assertRemoteControlAllowed, isFleetRemoteInvocation } from '../lib/browser/remote-control.js';
 import { getConfigValue, setConfigValue, unsetConfigValue } from '../lib/device-config.js';
 import { isInteractiveTerminal } from './utils.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { buildHar } from '../lib/browser/har.js';
 import { getCliVersion } from '../lib/version.js';
 import { runBrowserIPCStream } from '../lib/browser/stream.js';
+import { machineId } from '../lib/machine-id.js';
+/**
+ * Task name inferred from the local task→device index when `--task` was
+ * omitted and this session owns exactly one open task. Set by the page-verb
+ * preAction hook; consumed by {@link resolveTaskName}.
+ */
+let inferredTaskName;
 /**
  * Resolve which browser task a command targets. Order:
  *   1. `--task <name>` flag (explicit per-command override)
  *   2. `$AGENTS_BROWSER_TASK` (optional shell default)
- *   3. `undefined` — the daemon resolves from the caller's identity
- *      (session / launch id stamped in sendIPCRequest)
+ *   3. the local task-index match for this session (exactly one)
+ *   4. `undefined` — the daemon resolves from the caller's identity
+ *
+ * `--device` on a page verb is rejected here so commander-parsed flags cannot
+ * silently re-route a later verb. Bind the device at `start`.
  *
  * `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.device) {
+        const route = resolveTaskRoute({ device: opts.device });
+        console.error(route.kind === 'reject-device' ? route.message : REJECT_DEVICE_MESSAGE);
+        process.exit(1);
+    }
     if (opts.task)
         return opts.task;
     const fromEnv = process.env.AGENTS_BROWSER_TASK;
     if (fromEnv)
         return fromEnv;
-    return undefined;
+    return inferredTaskName;
 }
 // `-t` is taken by `--tab` on most commands, so `--task` is long-form only.
 // 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, else the caller\'s live task)';
+const DEVICE_ON_PAGE_VERB_FLAG = '--device <name>';
+const DEVICE_ON_PAGE_VERB_DESC = 'Not valid here — bind the device at `agents browser start --device`';
+const TASK_ROUTED_COMMANDS = new Set([
+    'stream',
+    'done',
+    'stop',
+    'navigate',
+    'goto',
+    'tab',
+    'tabs',
+    'screenshot',
+    'pdf',
+    'evaluate',
+    'refs',
+    'click',
+    'type',
+    'press',
+    'hover',
+    'scroll',
+    'upload',
+    'set',
+    'console',
+    'errors',
+    'requests',
+    'logs',
+    'responsebody',
+    'wait',
+    'download',
+    'record',
+    'waitdownload',
+]);
+function commandPath(actionCommand) {
+    const parts = [];
+    let current = actionCommand;
+    while (current) {
+        const name = current.name();
+        if (name === 'agents' || name === 'browser')
+            break;
+        parts.unshift(name);
+        current = current.parent ?? null;
+    }
+    return parts;
+}
+function callerSessionId() {
+    return process.env.AGENT_SESSION_ID || process.env.AGENTS_SESSION_ID;
+}
+function callerLaunchId() {
+    return process.env.AGENT_LAUNCH_ID;
+}
+function browserForwardedArgv() {
+    const raw = process.argv.slice(2);
+    const withCommand = raw[0] === 'browser' ? raw : ['browser', ...raw];
+    return stripRoutingFlags(withCommand, HOST_ROUTING_SPECS);
+}
+async function dispatchBrowserToDevice(device, forwardedArgs, mode) {
+    const host = await resolveHost(device);
+    if (!host) {
+        throw new Error(`Unknown device "${device}". Next: agents devices list`);
+    }
+    const target = sshTargetFor(host);
+    const remoteOs = resolveRemoteOsSync(host.name);
+    const env = withActorEnv({ AGENTS_FLEET_REMOTE: '1' });
+    const remoteCmd = buildRemoteAgentsInvocation(forwardedArgs, undefined, remoteOs, env);
+    if (mode === 'stream') {
+        const code = streamAgentsOnHost(host, forwardedArgs, {
+            interactive: !!process.stdout.isTTY && !process.argv.includes('--no-tty'),
+            extraEnv: { AGENTS_FLEET_REMOTE: '1' },
+            remoteOs,
+            target,
+        });
+        return { code, stdout: '', stderr: '' };
+    }
+    const sshOpts = passthroughSshOptions(host, false);
+    const result = sshExec(target, remoteCmd, {
+        multiplex: sshOpts.multiplex,
+        extraSshArgs: sshOpts.extraSshArgs,
+    });
+    return {
+        code: result.code ?? 1,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+async function pullRemoteFile(device, remotePath, localPath) {
+    const host = await resolveHost(device);
+    if (!host) {
+        throw new Error(`Unknown device "${device}". Next: agents devices list`);
+    }
+    const target = sshTargetFor(host);
+    fs.mkdirSync(path.dirname(path.resolve(localPath)), { recursive: true });
+    const sshOpts = passthroughSshOptions(host, false);
+    const copied = spawnSync('scp', [...sshOpts.extraSshArgs, ...SSH_OPTS, `${target}:${remotePath}`, path.resolve(localPath)], { encoding: 'utf8' });
+    if (copied.status !== 0) {
+        throw new Error(`Failed to copy screenshot from ${device}:${remotePath}: ${(copied.stderr || copied.stdout || '').trim()}`);
+    }
+}
+function syncTaskIndex(request, response) {
+    if (!response.ok)
+        return;
+    if (request.action === 'stop' && request.profile && !request.task) {
+        unbindTasksForProfile(request.profile);
+        return;
+    }
+    if (request.action === 'gc') {
+        if (!request.dryRun) {
+            for (const closed of response.reaped?.closed ?? []) {
+                unbindTask(closed.task);
+            }
+        }
+        return;
+    }
+    const name = response.task ?? request.task ?? request.taskName;
+    if (!name)
+        return;
+    if (request.action === 'done' || (request.action === 'stop' && request.task)) {
+        unbindTask(name);
+        return;
+    }
+    if (request.action === 'start') {
+        const existing = getTaskBinding(name);
+        if (!existing) {
+            bindTask(name, {
+                device: machineId(),
+                profile: request.profile,
+                url: request.url,
+                sessionId: request.sessionId ?? callerSessionId(),
+                launchId: request.launchId ?? callerLaunchId(),
+                createdAt: Date.now(),
+            });
+        }
+        else if (request.url) {
+            updateTaskBinding(name, { url: request.url });
+        }
+        return;
+    }
+    if (request.url) {
+        const existing = getTaskBinding(name);
+        if (existing) {
+            updateTaskBinding(name, { url: request.url });
+        }
+        else {
+            bindTask(name, {
+                device: machineId(),
+                profile: request.profile,
+                url: request.url,
+                sessionId: request.sessionId ?? callerSessionId(),
+                launchId: request.launchId ?? callerLaunchId(),
+                createdAt: Date.now(),
+            });
+        }
+        return;
+    }
+    if (!getTaskBinding(name)) {
+        bindTask(name, {
+            device: machineId(),
+            profile: request.profile,
+            sessionId: request.sessionId ?? callerSessionId(),
+            launchId: request.launchId ?? callerLaunchId(),
+            createdAt: Date.now(),
+        });
+    }
+}
+async function sendIPCRequest(request, opts) {
+    const response = await sendRawIPCRequest(request, opts);
+    syncTaskIndex(request, response);
+    return response;
+}
+function assertDeviceDeclaresProfile(device, profileName) {
+    const declared = declaringDevices(profileName);
+    if (declared.includes(device))
+        return;
+    const where = declared.length > 0
+        ? `Declared on: ${declared.join(', ')}.`
+        : 'No device declares that profile.';
+    throw new Error(`Device "${device}" does not declare browser profile "${profileName}". ${where}\n` +
+        `Next: run \`agents browser profiles add ${profileName} --browser <b>\` on ${device}.`);
+}
 // 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: ['use', 'start', 'done', 'status', 'gc'] },
+    { title: 'Session lifecycle', names: ['use', 'start', 'done', 'status', 'prune'] },
     { title: 'Fast action loop', names: ['stream'] },
     {
         title: 'Drive the page',
@@ -86,8 +290,10 @@ export function registerBrowserCommand(program) {
       # Keep one process and daemon socket warm for repeated actions
       agents browser stream --task "$AGENTS_BROWSER_TASK"
 
-      # Drive another machine's browser (needs its consent — see remote-control)
-      agents browser start --device zion
+      # Bind a device at start; later verbs resolve it from the task
+      agents browser start --task post --device zion --url https://x.com/
+      agents browser type --task post --ref @e3 "hello"
+      agents browser screenshot --task post
 
       # Browse a task-heavy profile's captures: one row per task, not per file
       agents browser sessions
@@ -99,7 +305,7 @@ export function registerBrowserCommand(program) {
       agents browser done
 
       # Close tabs the daemon's own reaper would have caught on its next 5-min tick
-      agents browser gc --dry-run
+      agents browser prune --dry-run
     `,
         notes: `
       Most agent workflows should use the 'browser' skill instead of raw subcommands.
@@ -233,27 +439,28 @@ function registerProfilesCommands(browser) {
     profiles
         .command('list')
         .alias('ls')
-        .description('List all browser profiles, with the store each lives in (local / fleet)')
-        .option('--json', 'Output machine-readable JSON')
+        .description('List all browser profiles and the devices declaring each one (WHERE)')
+        .option('--json', 'Output machine-readable JSON (includes devices + kind)')
         .action(async (opts) => {
-        const scoped = await listProfilesWithScope();
+        const allProfiles = await listProfiles();
         const configuredDefault = getConfiguredDefaultProfileName();
         if (opts.json) {
-            console.log(JSON.stringify(scoped.map(({ profile, scope }) => ({
+            console.log(JSON.stringify(allProfiles.map((profile) => ({
                 ...profile,
-                scope,
+                devices: profile.devices,
+                kind: profileKind(profile.name),
                 isConfiguredDefault: profile.name === configuredDefault,
             })), null, 2));
             return;
         }
-        if (scoped.length === 0) {
+        if (allProfiles.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))
+        for (const line of formatProfilesTable(allProfiles, configuredDefault))
             console.log(line);
     });
     profiles
@@ -284,6 +491,44 @@ function registerProfilesCommands(browser) {
         }
         console.log('Pick your default with: agents browser use <name>');
     });
+    profiles
+        .command('claim [name]')
+        .description('Move leftover central browser: profiles into this device\'s declaration file. Only profiles this machine can host are claimed; the rest stay central. Run on the machine that actually has the browser.')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (name, opts) => {
+        const canHostHere = (config) => isProfileLaunchableHere({
+            name: '_',
+            browser: config.browser,
+            binary: config.binary,
+            endpoints: config.endpoints,
+        });
+        let result;
+        try {
+            result = migrateCentralBrowserProfiles(canHostHere, name);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...result, device: machineId() }, null, 2));
+            return;
+        }
+        if (result.claimed.length === 0 && result.skipped.length === 0) {
+            console.log('No leftover central browser profiles to claim.');
+            return;
+        }
+        for (const claimed of result.claimed) {
+            console.log(`Claimed ${claimed} on ${machineId()}`);
+        }
+        for (const skipped of result.skipped) {
+            console.log(`Skipped ${skipped}: this machine cannot host it (browser/binary isn't installed here). ` +
+                `Run \`agents browser profiles claim ${skipped}\` on the machine that has that browser.`);
+        }
+        if (result.claimed.length === 0) {
+            console.log('No leftover central profiles this machine can host.');
+        }
+    });
     configureBrowserUseCommand(profiles.command('use [name]'));
     configureBrowserUseCommand(profiles.command('set-default [name]', { hidden: true }), true);
     profiles
@@ -317,9 +562,9 @@ function registerProfilesCommands(browser) {
     const VALID_BROWSERS = ['chrome', 'comet', 'chromium', 'brave', 'edge', 'arc', 'custom'];
     profiles
         .command('create <name>')
-        .description('Create a new browser profile (machine-local unless --fleet)')
+        .alias('add')
+        .description('Create a new browser profile on this device')
         .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')
@@ -330,8 +575,11 @@ function registerProfilesCommands(browser) {
         .option('--electron', 'Treat this profile as an Electron desktop app: never call Target.createTarget; bind to the visible window using --target-filter or the skip-invisible heuristic')
         .option('--target-filter <expr>', 'Pick the visible CDP page target when the app exposes more than one. Format: url:<substring> or title:<substring>')
         .action(async (name, opts) => {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            console.error('Profile name must be lowercase alphanumeric with hyphens');
+        try {
+            assertRegistrableProfileName(name);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
         if (!VALID_BROWSERS.includes(opts.browser)) {
@@ -370,22 +618,22 @@ function registerProfilesCommands(browser) {
             height: DEFAULT_VIEWPORT.height,
         };
         if (opts.window) {
-            const m = String(opts.window).match(/^(\d+)x(\d+)$/);
-            if (!m) {
+            const size = parseWindowSize(String(opts.window));
+            if (!size) {
                 console.error(`--window must be WxH, e.g. ${DEFAULT_VIEWPORT.width}x${DEFAULT_VIEWPORT.height}`);
                 process.exit(1);
             }
-            viewport.width = parseInt(m[1], 10);
-            viewport.height = parseInt(m[2], 10);
+            viewport.width = size.width;
+            viewport.height = size.height;
         }
         if (opts.position) {
-            const m = String(opts.position).match(/^(-?\d+),(-?\d+)$/);
-            if (!m) {
+            const pos = parseWindowPosition(String(opts.position));
+            if (!pos) {
                 console.error('--position must be X,Y, e.g. 80,80');
                 process.exit(1);
             }
-            viewport.x = parseInt(m[1], 10);
-            viewport.y = parseInt(m[2], 10);
+            viewport.x = pos.x;
+            viewport.y = pos.y;
         }
         const profile = {
             name,
@@ -399,14 +647,169 @@ function registerProfilesCommands(browser) {
             chrome: opts.headless ? { headless: true } : undefined,
             viewport,
         };
-        await createProfile(profile, { fleet: !!opts.fleet });
-        console.log(`Created profile: ${name} (${opts.fleet ? 'fleet-synced — visible on every machine' : 'machine-local'})`);
+        await createProfile(profile);
+        const port = extractConfiguredPort(profile);
+        console.log(port !== undefined
+            ? `Added "${name}" on ${machineId()} (port ${port}).`
+            : `Added "${name}" on ${machineId()}.`);
         // 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)) {
             console.error(`warning: secrets bundle "${opts.secrets}" does not exist yet. Create it with: agents secrets create ${opts.secrets}`);
         }
     });
+    profiles
+        .command('edit <name>')
+        .description('Edit an existing profile in place (stays in the store it already lives in)')
+        // Declared only so the action can explain WHY the browser type is not
+        // editable. Without it commander rejects `-b` as an unknown option before
+        // the action runs, and the delete-and-recreate guidance never reaches anyone.
+        .option('-b, --browser <type>', 'Not editable — see the error for the delete-and-recreate path')
+        .option('-d, --description <text>', "Profile description (pass '' to clear)")
+        .option('-e, --endpoint <url>', 'Replace the endpoint list (repeatable)', collect, [])
+        .option('-s, --secrets <bundle>', 'Secrets bundle to inject')
+        .option('--headless', 'Run in headless mode')
+        .option('--no-headless', 'Run headed')
+        .option('--window <WxH>', 'Window size in CSS pixels')
+        .option('--position <X,Y>', 'Window position on screen, e.g. 80,80')
+        .option('--binary <path>', 'Absolute path to the browser/app binary')
+        .option('--electron', 'Treat this profile as an Electron desktop app')
+        .option('--no-electron', 'Stop treating it as an Electron app')
+        .option('--target-filter <expr>', "url:<substring> or title:<substring>; requires --electron (pass '' to clear)")
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (name, opts) => {
+        // The browser type and the name are identity, not settings: both key the
+        // on-disk runtime dir and any live `<name>@<endpoint>` connection, so
+        // changing either orphans the cached browser data (and its logins).
+        if (opts.browser) {
+            console.error('browser type is not editable — it keys the on-disk profile cache. ' +
+                `Remove and recreate instead: agents browser profiles remove ${name} && agents browser profiles create ${name} -b <type>`);
+            process.exit(1);
+        }
+        if (opts.targetFilter) {
+            const parsed = parseTargetFilter(String(opts.targetFilter));
+            if (!parsed) {
+                console.error('--target-filter must be url:<substring> or title:<substring> (non-empty value, no leading whitespace)');
+                process.exit(1);
+            }
+        }
+        const patch = {};
+        if (opts.description !== undefined)
+            patch.description = opts.description || undefined;
+        if (opts.endpoint && opts.endpoint.length > 0)
+            patch.endpoints = opts.endpoint;
+        if (opts.secrets !== undefined)
+            patch.secrets = opts.secrets;
+        if (opts.binary !== undefined)
+            patch.binary = opts.binary;
+        if (opts.targetFilter !== undefined)
+            patch.targetFilter = opts.targetFilter || undefined;
+        // commander maps --electron/--no-electron and --headless/--no-headless onto
+        // one boolean each, and leaves it undefined when neither was passed.
+        if (opts.electron !== undefined)
+            patch.electron = opts.electron || undefined;
+        if (opts.headless !== undefined || opts.window || opts.position) {
+            const current = await getProfile(name);
+            if (!current) {
+                console.error(`Profile "${name}" does not exist`);
+                process.exit(1);
+            }
+            if (opts.headless !== undefined) {
+                const chrome = { ...current.chrome };
+                if (opts.headless)
+                    chrome.headless = true;
+                else
+                    delete chrome.headless;
+                // `{ headless: undefined }` is truthy, so profileToConfig would persist
+                // a bare `chrome: {}` into the YAML and the change-detector would report
+                // a phantom edit on an already-headed profile. Drop the key entirely.
+                patch.chrome = Object.keys(chrome).length > 0 ? chrome : undefined;
+            }
+            if (opts.window || opts.position) {
+                const viewport = { ...(current.viewport ?? { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height }) };
+                if (opts.window) {
+                    const size = parseWindowSize(String(opts.window));
+                    if (!size) {
+                        console.error('--window must be WxH, e.g. 1512x982');
+                        process.exit(1);
+                    }
+                    viewport.width = size.width;
+                    viewport.height = size.height;
+                }
+                if (opts.position) {
+                    const pos = parseWindowPosition(String(opts.position));
+                    if (!pos) {
+                        console.error('--position must be X,Y, e.g. 80,80');
+                        process.exit(1);
+                    }
+                    viewport.x = pos.x;
+                    viewport.y = pos.y;
+                }
+                patch.viewport = viewport;
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            console.error('Nothing to edit. Pass at least one field, e.g. -d "<description>".');
+            process.exit(1);
+        }
+        let result;
+        try {
+            result = await editProfile(name, patch);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ ...result.profile, devices: result.devices, changed: result.changed }, null, 2));
+        }
+        else if (result.changed.length === 0) {
+            console.log(`No change: ${name} already had those values.`);
+        }
+        else {
+            console.log(`Updated ${name} on ${machineId()}: ${result.changed.join(', ')}`);
+        }
+        if (patch.secrets && !bundleExists(patch.secrets)) {
+            console.error(`warning: secrets bundle "${patch.secrets}" does not exist yet. Create it with: agents secrets create ${patch.secrets}`);
+        }
+    });
+    profiles
+        .command('rename <from> <to>')
+        .description("Rename a profile, moving its browser data with it (logins survive)")
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (from, to, opts) => {
+        let res;
+        try {
+            res = await renameProfile(from, to);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({ from, to, ...res }, null, 2));
+            return;
+        }
+        console.log(`Renamed ${from} -> ${to} on ${machineId()}`);
+        if (res.movedDirs.length > 0) {
+            console.log(`  moved ${res.movedDirs.length} browser data dir${res.movedDirs.length === 1 ? '' : 's'} — logins preserved`);
+        }
+        if (res.repointedDefault) {
+            console.log(`  browser.profile now points at ${to}`);
+        }
+        if (res.repointedViewer) {
+            console.log(`  browser.viewer now points at ${to}`);
+        }
+        if (res.stalePins.length > 0) {
+            const devices = [...new Set(res.stalePins.map((p) => p.device))];
+            const one = devices.length === 1;
+            console.error(`warning: ${devices.join(', ')} still ${one ? 'pins' : 'pin'} "${from}" in ` +
+                `${one ? 'its' : 'their'} own device config. Fix with:`);
+            for (const pin of res.stalePins) {
+                console.error(`  agents config set ${pin.key} ${to} --device ${pin.device}`);
+            }
+        }
+    });
     profiles
         .command('show <name>')
         .description('Show profile details')
@@ -485,8 +888,9 @@ function registerProfilesCommands(browser) {
         }
     });
     profiles
-        .command('delete <name>')
-        .description('Delete a browser profile (drops YAML config + all cached runtime dirs)')
+        .command('remove <name>')
+        .alias('delete')
+        .description('Remove 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);
@@ -519,24 +923,41 @@ function registerProfilesCommands(browser) {
     });
     profiles
         .command('prune')
-        .description('Remove dead machine-local profiles: browser not installed here, or never started')
+        .description('Remove dead profiles this device declares: 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 });
+        const plan = await buildProfilePrunePlan();
         if (!opts.dryRun)
             await pruneProfiles(plan);
         if (opts.json) {
             console.log(JSON.stringify({ dryRun: !!opts.dryRun, ...plan }, null, 2));
             return;
         }
+        // A misfiled profile is never a prune candidate — the entry belongs to the
+        // device that declared it, not to this one — so without this it would only
+        // ever surface in --json. It is the one kept-reason a user has to act on.
+        const misfiled = plan.kept.filter((k) => k.misfiled);
+        const reportMisfiled = () => {
+            if (misfiled.length === 0)
+                return;
+            console.log('');
+            console.log(`${misfiled.length} profile${misfiled.length === 1 ? '' : 's'} ${misfiled.length === 1 ? 'is' : 'are'} misfiled — ` +
+                `declared on another device but bound to a loopback port, so the name resolves to ` +
+                `this machine's own browser rather than the declaring device's:`);
+            for (const k of misfiled) {
+                console.log(`  ${k.name} — ${k.why}`);
+            }
+            console.log('Re-declare each on the machine that owns the browser. Nothing was moved for you.');
+            console.log('(Prune never deletes these — the declaring device owns the entry.)');
+        };
         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}`);
             }
+            reportMisfiled();
             return;
         }
         const verb = opts.dryRun ? 'Would remove' : 'Removed';
@@ -547,6 +968,7 @@ function registerProfilesCommands(browser) {
                 : '';
             console.log(`  ${c.name} (${c.scope}) — ${PRUNE_REASON_TEXT[c.reason]}${cache}`);
         }
+        reportMisfiled();
         if (opts.dryRun) {
             console.log('');
             console.log('Nothing was changed. Re-run without --dry-run to apply.');
@@ -554,16 +976,18 @@ function registerProfilesCommands(browser) {
     });
     setHelpSections(profiles, {
         examples: `
-      # What exists here, and whether each is this machine's or the whole fleet's
+      # WHERE is the devices whose own file declares the name
       agents browser profiles list
 
-      # Create one — machine-local by default
+      # Create one on this device
+      agents browser profiles add work --browser chrome
       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
+      # Claim leftover central profiles on the machine that hosts the browser
+      agents browser profiles claim
+      agents browser profiles claim comet-local
 
-      # Clean up dead ones: check first, then apply
+      # Clean up dead ones this device declares: check first, then apply
       agents browser profiles prune --dry-run
       agents browser profiles prune
 
@@ -571,22 +995,24 @@ function registerProfilesCommands(browser) {
       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.
+      A device declares its own browsers in its own \`devices/<machine>/agents.yaml\`.
+      A name declared by exactly one device is identity-bearing; a name declared
+      by several is fungible. Leftover central \`browser:\` entries are claimed
+      with \`agents browser profiles claim\` on the machine that hosts the browser.
 
       In \`list\`, the \`*\` marker means "this machine's configured default"
       (\`agents browser start\` with no --profile). The auto-detected profile is
       named \`auto-chrome\`; \`default\` is only an ALIAS for whichever profile
       this machine is configured to use, resolved the same way by every command.
 
-      \`prune\` never removes a profile that is in use, the configured default, the
-      auto-detected \`auto-chrome\`, or (without --fleet) a fleet-synced one.
+      \`prune\` only considers profiles this device declares. It never removes a
+      profile that is in use, the configured default, or the auto-detected
+      \`auto-chrome\`.
     `,
     });
     profiles
         .command('doctor <name>')
-        .description('Diagnose a browser profile: binary, port, user-data-dir, onboarding state')
+        .description('Diagnose a browser profile: where it is declared, binary, port, user-data-dir, onboarding state')
         .action(async (name) => {
         const profile = await getProfile(name);
         if (!profile) {
@@ -594,6 +1020,29 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         const checks = [];
+        // 0. Declaration topology. An identity-bearing profile declared by a
+        //    different device cannot be diagnosed through a loopback CDP endpoint
+        //    on this one — that is the original comet-local bug. Checked first
+        //    because it invalidates every local check.
+        const misfiled = identityLoopbackMismatch(profile);
+        const kind = profileKind(profile.name);
+        const where = profile.devices.length > 0 ? profile.devices.join(', ') : 'no device';
+        checks.push(misfiled.misfiled
+            ? { label: 'where', ok: false, detail: misfiled.why }
+            : {
+                label: 'where',
+                ok: true,
+                detail: kind
+                    ? `${kind}, declared on ${where}`
+                    : `declared on ${where}`,
+            });
+        if (misfiled.misfiled) {
+            for (const c of checks) {
+                const marker = c.ok ? 'OK  ' : 'FAIL';
+                console.log(`${marker}  ${c.label.padEnd(15)} ${c.detail}`);
+            }
+            process.exit(1);
+        }
         // 1. Binary exists for declared browser type, and is a real executable we
         //    can drive — not a distro launcher script. findBrowserPath already
         //    unwraps the known Chromium wrappers to their ELF; if it still hands
@@ -754,6 +1203,80 @@ function registerProfilesCommands(browser) {
     });
 }
 function registerTaskCommands(browser) {
+    browser.hook('preAction', async (_thisCommand, actionCommand) => {
+        inferredTaskName = undefined;
+        if (isFleetRemoteInvocation())
+            return;
+        const pathNames = commandPath(actionCommand);
+        const top = pathNames[0];
+        if (!top || !TASK_ROUTED_COMMANDS.has(top))
+            return;
+        if (pathNames.length === 1 && top === 'start')
+            return;
+        const opts = actionCommand.opts();
+        const deviceFlag = opts.device ?? flagValue(process.argv.slice(2), 'device', 'D');
+        const taskFlag = opts.task ?? flagValue(process.argv.slice(2), 'task');
+        // Reject --device on every later verb, including `stop --profile`.
+        if (deviceFlag) {
+            console.error(REJECT_DEVICE_MESSAGE);
+            process.exit(1);
+        }
+        if (top === 'stop' && opts.profile && !taskFlag)
+            return;
+        const route = resolveTaskRoute({
+            task: taskFlag ?? process.env.AGENTS_BROWSER_TASK,
+            sessionId: callerSessionId(),
+            launchId: callerLaunchId(),
+        });
+        if (route.kind !== 'proceed') {
+            console.error(route.message);
+            process.exit(1);
+        }
+        inferredTaskName = route.task;
+        if (isSelfHost(route.device) || !route.task)
+            return;
+        const forwarded = browserForwardedArgv();
+        if (route.task && !forwarded.includes('--task')) {
+            forwarded.push('--task', route.task);
+        }
+        const outputPath = top === 'screenshot'
+            ? actionCommand.opts().output ??
+                flagValue(process.argv.slice(2), 'output', 'o')
+            : undefined;
+        if (top === 'screenshot' && outputPath) {
+            const withoutOutput = stripRoutingFlags(forwarded, [
+                { long: 'output', short: 'o', takesValue: true },
+            ]);
+            const captured = await dispatchBrowserToDevice(route.device, withoutOutput, 'capture');
+            if (captured.code !== 0) {
+                process.stderr.write(captured.stderr);
+                process.exit(captured.code);
+            }
+            const remotePath = captured.stdout
+                .split('\n')
+                .map((line) => line.trim())
+                .find((line) => line.length > 0);
+            if (!remotePath) {
+                console.error(`Remote screenshot on ${route.device} produced no path.`);
+                process.exit(1);
+            }
+            try {
+                await pullRemoteFile(route.device, remotePath, outputPath);
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+            const saved = path.resolve(outputPath);
+            console.log(saved);
+            process.exit(0);
+        }
+        const result = await dispatchBrowserToDevice(route.device, forwarded, 'stream');
+        if (result.code === 0 && (top === 'done' || top === 'stop') && route.task) {
+            unbindTask(route.task);
+        }
+        process.exit(result.code);
+    });
     browser
         .command('remote-control [state]')
         .description("Allow or deny other fleet machines driving THIS machine's browser over `browser --device`. " +
@@ -794,6 +1317,7 @@ function registerTaskCommands(browser) {
         .command('stream')
         .description('Keep one process and daemon IPC socket open; read NDJSON requests from stdin and write NDJSON responses')
         .option(TASK_OPTION_FLAG, 'Default task for requests that omit `task` (defaults to $AGENTS_BROWSER_TASK)')
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .action(async (opts) => {
         await runBrowserIPCStream({
             input: process.stdin,
@@ -829,6 +1353,7 @@ function registerTaskCommands(browser) {
         .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('--device <name>', 'Device that hosts this task; later verbs resolve it from --task (not valid on page verbs)')
         .option('--fresh', 'Always open a new tab, skipping the reclaim of a tab an abandoned task is holding on that URL')
         .option('--no-skills', 'Skip auto-discovery of site-specific SKILL.md from ~/.agents/skills/browser/domain-skills/')
         .option('--record', 'Start recording right after the tab opens (shorthand for `agents browser record start` as a follow-up)')
@@ -836,9 +1361,11 @@ 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 --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.
+        // Fast-fail copy of the consent gate, so a refused start never resolves or
+        // auto-creates a profile. The AUTHORITATIVE gate is in the daemon
+        // (BrowserService.start / resolveOrCreateTask, via
+        // assertRemoteControlAllowedForRequest) — it has to be, because the page
+        // verbs create a browser implicitly and never reach this command.
         try {
             assertRemoteControlAllowed();
         }
@@ -882,6 +1409,52 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
         }
+        const deviceName = opts.device;
+        if (deviceName) {
+            const lowered = deviceName.toLowerCase();
+            if (lowered === 'all' || lowered === 'auto') {
+                console.error(`--device ${deviceName} is not valid on \`agents browser start\`: a task lives on one device.\n` +
+                    `Next: agents browser start --task <name> --device <device>`);
+                process.exit(1);
+            }
+            try {
+                assertDeviceDeclaresProfile(deviceName, profileName);
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+            if (!isSelfHost(deviceName) && !isFleetRemoteInvocation()) {
+                try {
+                    const result = await dispatchBrowserToDevice(deviceName, browserForwardedArgv(), 'capture');
+                    process.stdout.write(result.stdout);
+                    process.stderr.write(result.stderr);
+                    if (result.code !== 0)
+                        process.exit(result.code);
+                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
+                    if (!taskName) {
+                        console.error(`Remote start on ${deviceName} produced no task name.`);
+                        process.exit(1);
+                    }
+                    bindTask(taskName, {
+                        device: deviceName,
+                        profile: profileName,
+                        url: opts.url,
+                        sessionId: callerSessionId(),
+                        launchId: callerLaunchId(),
+                        createdAt: Date.now(),
+                    });
+                    if (!result.stderr.includes(`started on ${deviceName}`)) {
+                        console.error(`Task "${taskName}" started on ${deviceName} (profile: ${profileName}).`);
+                    }
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exit(1);
+                }
+                return;
+            }
+        }
         // Grounded login guardrail: if the opening URL is a known login-gated
         // service and the resolved profile has no session for it, say so on stderr
         // and name a profile that IS logged in. Reads the profile's real cookie DB
@@ -917,18 +1490,27 @@ function registerTaskCommands(browser) {
             console.error(response.error);
             process.exit(1);
         }
+        const boundDevice = deviceName && isSelfHost(deviceName) ? deviceName : machineId();
+        if (response.task) {
+            bindTask(response.task, {
+                device: boundDevice,
+                profile: profileName,
+                url: opts.url,
+                sessionId: callerSessionId(),
+                launchId: callerLaunchId(),
+                createdAt: Date.now(),
+            });
+        }
         // stdout: just the resolved name, one line, no decoration. Lets callers do:
         //   export AGENTS_BROWSER_TASK=$(agents browser start --profile work)
         console.log(response.task);
         // stderr: human-friendly commentary so a TTY user still sees what happened.
         // Shell substitution captures stdout only, so $(...) stays clean.
+        console.error(`Task "${response.task}" started on ${boundDevice} (profile: ${profileName}).`);
         if (opts.url && response.tabId) {
-            console.error(`Started task "${response.task}" with tab ${response.tabId}`);
-        }
-        else {
-            console.error(`Started task "${response.task}"`);
+            console.error(`Tab ${response.tabId}`);
         }
-        console.error('Tip: page verbs resolve this task from your session — --task only when running two at once.');
+        console.error('Tip: page verbs resolve this task from --task; --device is only valid on start.');
         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
@@ -965,6 +1547,7 @@ function registerTaskCommands(browser) {
         .command('done')
         .description('Complete a task and close its tabs (resolves from caller identity when --task is omitted)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .action(async (opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
@@ -985,6 +1568,7 @@ function registerTaskCommands(browser) {
         .command('stop')
         .description('Stop a browser task and close its tabs; with --profile, detach the whole profile (close browser + drop cached connection)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-p, --profile <name>', 'Detach the whole profile (incl. composite "name@endpoint") instead of stopping a single task')
         .action(async (opts) => {
         if (opts.profile) {
@@ -1016,7 +1600,8 @@ function registerTaskCommands(browser) {
         console.log(`Stopped task: ${response.task}`);
     });
     browser
-        .command('gc')
+        .command('prune')
+        .alias('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')
@@ -1053,11 +1638,44 @@ function registerTaskCommands(browser) {
             console.log(`  ${c.task}  (${c.profile}, ${c.reason})`);
         }
     });
+    browser
+        .command('show <url>')
+        .description('Open a URL for a human to read: goes to browser.viewer (default: browser.profile), and binds no task')
+        .option('--os-browser', 'Use the OS default handler instead of the configured viewer')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (url, opts) => {
+        // The entry point external tools need. `navigate` binds a task, which the
+        // abandoned-task reaper closes when the calling session ends — wrong for a
+        // page a person is reading. This does not.
+        const { showUrl, showFile } = await import('../lib/open-url.js');
+        // `+` not `*` on the scheme body: `[a-z][a-z0-9+.-]*:` matches a Windows
+        // drive letter (`C:\Users\me\plan.html`), so a real path was treated as a
+        // URL. A scheme is at least two characters.
+        const isLocalFile = !/^[a-z][a-z0-9+.-]+:/i.test(url);
+        const outcome = isLocalFile
+            ? await showFile(path.resolve(url), { osBrowser: opts.osBrowser })
+            : await showUrl(url, { osBrowser: opts.osBrowser });
+        if (opts.json) {
+            console.log(JSON.stringify(outcome, null, 2));
+        }
+        else if (outcome.via === 'none') {
+            console.error(`Could not open a browser — open this yourself:\n  ${url}`);
+        }
+        else if (outcome.via === 'profile') {
+            console.log(`Shown in ${outcome.profile}: ${url}`);
+        }
+        else {
+            console.log(`Opened in the OS default browser: ${url}`);
+        }
+        if (outcome.via === 'none')
+            process.exit(1);
+    });
     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)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .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 (urlPos, opts) => {
@@ -1088,6 +1706,7 @@ function registerTaskCommands(browser) {
         .command('add')
         .description('Open URL in new tab (becomes current)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .requiredOption('--url <url>', 'URL to open in the new tab')
         .option('-p, --profile <name>', 'Browser profile')
         .action(async (opts) => {
@@ -1108,6 +1727,7 @@ function registerTaskCommands(browser) {
         .command('focus <tabId>')
         .description('Switch to tab (by ID, prefix, or URL substring)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .action(async (tabId, opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
@@ -1125,6 +1745,7 @@ function registerTaskCommands(browser) {
         .command('close [tabId]')
         .description('Close tab(s) — omit tabId to close all')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .action(async (tabId, opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
@@ -1142,6 +1763,7 @@ function registerTaskCommands(browser) {
         .command('tabs')
         .description('List tabs open for the current task')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
         const task = resolveTaskName(opts);
@@ -1177,6 +1799,7 @@ function registerTaskCommands(browser) {
         .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(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_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')
@@ -1197,17 +1820,22 @@ function registerTaskCommands(browser) {
             console.error(response.error);
             process.exit(1);
         }
+        // RUSH-3086: the daemon sandboxes writes to the runtime dir and silently
+        // ignores `-o` outside it. Honor the requested path here.
+        const savedPath = response.path
+            ? honorScreenshotOutput(opts.output, response.path)
+            : response.path;
         // stdout: just the path, so `P=$(agents browser screenshot)` works.
-        console.log(response.path);
+        console.log(savedPath);
         // stderr: human commentary with size + dimensions, so an agent can
         // see at a glance what was captured without `ls -l && file` round-trips.
         const size = humanizeBytes(response.bytes);
         const dims = response.width && response.height ? `${response.width}×${response.height}` : 'unknown size';
-        console.error(`Saved screenshot to ${response.path} (${size}, ${dims})`);
+        console.error(`Saved screenshot to ${savedPath} (${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);
+        if (!opts.output && savedPath) {
+            const dir = path.dirname(savedPath);
             console.error(`Tip: auto-saving to ${dir}. Pass --output <path> to choose a path.`);
         }
     });
@@ -1215,6 +1843,7 @@ function registerTaskCommands(browser) {
         .command('pdf [output]')
         .description('Export the current tab as PDF via CDP Page.printToPDF — auto-saved under sessions/<task>/ when [output] is omitted')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .action(async (output, opts) => {
         const task = resolveTaskName(opts);
@@ -1241,6 +1870,7 @@ function registerTaskCommands(browser) {
         .alias('eval')
         .description('Evaluate JavaScript in current tab')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .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')
@@ -1590,6 +2220,7 @@ function registerTaskCommands(browser) {
         .command('refs')
         .description('Get DOM refs for interactive elements')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_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')
@@ -1632,6 +2263,7 @@ function registerTaskCommands(browser) {
         .command('click [ref]')
         .description('Click an element by ref, or raw coordinates with --at X,Y')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--at <x,y>', 'Click viewport coordinates (e.g. --at 320,540), bypassing ref resolution')
         .action(async (ref, opts) => {
@@ -1674,6 +2306,7 @@ function registerTaskCommands(browser) {
         .command('type <ref>')
         .description('Type text into an element by ref')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--text <text>', 'Text to type (use quotes for spaces/special chars)')
         .option('--secret <ref>', 'Resolve <bundle>/<KEY> from `agents secrets` and type the value. The secret is resolved in-process and never printed to stdout or the transcript. Alternative to --text.')
@@ -1738,6 +2371,7 @@ function registerTaskCommands(browser) {
         .command('press <key>')
         .description('Press a key (Enter, Tab, Escape, etc)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .action(async (key, opts) => {
         const task = resolveTaskName(opts);
@@ -1757,6 +2391,7 @@ function registerTaskCommands(browser) {
         .command('hover <ref>')
         .description('Hover over an element by ref')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .action(async (ref, opts) => {
         const task = resolveTaskName(opts);
@@ -1776,6 +2411,7 @@ function registerTaskCommands(browser) {
         .command('scroll')
         .description('Scroll the page by pixel amount (negatives scroll up/left)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_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)
@@ -1810,6 +2446,7 @@ function registerTaskCommands(browser) {
         .command('upload')
         .description('Upload file(s) — supports hidden file inputs, drag-drop targets, and OS chooser interception')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-r, --ref <n>', 'Ref of the upload target element (file input or drop zone)', (v) => parseInt(v, 10))
         .option('--trigger <n>', 'Ref of a button that opens the OS file chooser (Pattern C)', (v) => parseInt(v, 10))
@@ -1861,6 +2498,7 @@ function registerTaskCommands(browser) {
         .command('viewport <width> <height>')
         .description('Set viewport size')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-m, --mobile', 'Enable mobile emulation')
         .option('-s, --scale <factor>', 'Device scale factor', parseFloat)
@@ -1885,6 +2523,7 @@ function registerTaskCommands(browser) {
         .command('device <device-name>')
         .description('Emulate a device (iPhone 14, iPad, MacBook Pro)')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .action(async (deviceName, opts) => {
         const task = resolveTaskName(opts);
@@ -1915,6 +2554,7 @@ function registerTaskCommands(browser) {
         .command('console')
         .description('Read console logs from a tab')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_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')
@@ -1945,6 +2585,7 @@ function registerTaskCommands(browser) {
         .command('errors')
         .description('Read page errors from a tab')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--clear', 'Clear errors after reading')
         .action(async (opts) => {
@@ -1977,6 +2618,7 @@ function registerTaskCommands(browser) {
         .command('requests')
         .description('Read captured network requests. --format har emits a HAR 1.2 JSON document.')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-f, --filter <text>', 'Filter URLs containing text')
         .option('--clear', 'Clear requests after reading')
@@ -2022,6 +2664,7 @@ function registerTaskCommands(browser) {
         .command('logs')
         .description('Read merged rush-app + rush-cli JSONL logs for a task')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_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)')
@@ -2060,6 +2703,7 @@ function registerTaskCommands(browser) {
         .command('responsebody <url-pattern>')
         .description('Wait for and read a response body by URL pattern')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_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)
@@ -2084,6 +2728,7 @@ function registerTaskCommands(browser) {
         .command('wait')
         .description('Wait for a condition')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--time <ms>', 'Wait for milliseconds')
         .option('--selector <css>', 'Wait for CSS selector to appear')
@@ -2138,6 +2783,7 @@ function registerTaskCommands(browser) {
         .command('download')
         .description("Set the download directory for a task (defaults to the profile's downloads dir)")
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-p, --path <dir>', "Download directory path (default: the profile's downloads dir)")
         .action(async (opts) => {
@@ -2170,6 +2816,7 @@ function registerTaskCommands(browser) {
         .command('start')
         .description('Start recording — auto-saved under sessions/<task>/recordings/. Bounded by --fps, --duration, --max-mb.')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('--fps <n>', 'Frames per second (1–30, default 5)', (v) => parseInt(v, 10))
         .option('--duration <sec>', 'Hard duration cap in seconds (default 60)', (v) => parseInt(v, 10))
@@ -2197,6 +2844,7 @@ function registerTaskCommands(browser) {
         .command('stop')
         .description('Stop an in-progress recording')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .action(async (opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({ action: 'record-stop', task });
@@ -2213,6 +2861,7 @@ function registerTaskCommands(browser) {
         .command('waitdownload')
         .description('Wait for a download to complete')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('--timeout <ms>', 'Timeout in milliseconds', parseInt)
         .action(async (opts) => {
         const task = resolveTaskName(opts);