@phnx-labs/agents-cli 1.22.47 → 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, editProfile, moveProfileScope, renameProfile, assertRegistrableProfileName, misfiledFleetProfile, } 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 { 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')
@@ -402,8 +647,11 @@ 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)) {
@@ -435,7 +683,7 @@ function registerProfilesCommands(browser) {
         // 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. ' +
-                `Delete and recreate instead: agents browser profiles delete ${name} && agents browser profiles create ${name} -b <type>`);
+                `Remove and recreate instead: agents browser profiles remove ${name} && agents browser profiles create ${name} -b <type>`);
             process.exit(1);
         }
         if (opts.targetFilter) {
@@ -513,17 +761,13 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         if (opts.json) {
-            console.log(JSON.stringify({ ...result.profile, scope: result.scope, changed: result.changed }, null, 2));
+            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} (${result.scope}): ${result.changed.join(', ')}`);
-        }
-        if (result.fleetCopyLeftStale) {
-            console.error(`warning: "${name}" is machine-local by rule, so the edit was written to this machine only. ` +
-                `The fleet-synced copy still holds the old values on every other box.`);
+            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}`);
@@ -546,7 +790,7 @@ function registerProfilesCommands(browser) {
             console.log(JSON.stringify({ from, to, ...res }, null, 2));
             return;
         }
-        console.log(`Renamed ${from} -> ${to} (${res.scope})`);
+        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`);
         }
@@ -566,37 +810,6 @@ function registerProfilesCommands(browser) {
             }
         }
     });
-    profiles
-        .command('scope <name> <scope>')
-        .description('Move a profile between the fleet-synced store and this machine (local|fleet)')
-        .option('--json', 'Output machine-readable JSON')
-        .action(async (name, scope, opts) => {
-        if (scope !== 'local' && scope !== 'fleet') {
-            console.error('scope must be `local` or `fleet`');
-            process.exit(1);
-        }
-        let moved;
-        try {
-            moved = await moveProfileScope(name, scope);
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
-        if (opts.json) {
-            console.log(JSON.stringify({ profile: name, ...moved }, null, 2));
-            return;
-        }
-        if (moved.from === moved.to) {
-            console.log(`${name} is already ${scope}.`);
-            return;
-        }
-        console.log(`Moved ${name}: ${moved.from} -> ${moved.to}`);
-        if (scope === 'local') {
-            console.error(`note: ${name} is no longer visible on any other machine. ` +
-                `Run this ON the machine that owns the browser — the surviving copy is this one.`);
-        }
-    });
     profiles
         .command('show <name>')
         .description('Show profile details')
@@ -675,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);
@@ -709,33 +923,33 @@ 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 fleet profile is never a prune candidate (deleting a fleet
-        // entry deletes it everywhere), so without this it would only ever surface
-        // in --json. It is the one kept-reason a user has to act on.
+        // 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} fleet profile${misfiled.length === 1 ? '' : 's'} ${misfiled.length === 1 ? 'is' : 'are'} misfiled — ` +
-                `fleet-synced but bound to a local port, so the name means a different browser on every machine:`);
+            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} — agents browser profiles scope ${k.name} local`);
+                console.log(`  ${k.name} — ${k.why}`);
             }
-            console.log('Run that on the machine that owns each browser. Nothing was moved for you.');
-            console.log('(Prune never deletes these — removing a fleet entry removes it everywhere.)');
+            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.');
@@ -762,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
 
@@ -779,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) {
@@ -802,15 +1020,29 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         const checks = [];
-        // 0. Store scope. A fleet-synced profile whose endpoint is loopback cdp://
-        //    means a DIFFERENT browser on every machine — the name lies everywhere
-        //    but here. Checked first because it invalidates the reading of every
-        //    check below on any other box.
-        const scoped = (await listProfilesWithScope()).find((p) => p.profile.name === name);
-        const misfiled = scoped ? misfiledFleetProfile(profile, scoped.scope) : { misfiled: false };
+        // 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: 'scope', ok: false, detail: misfiled.why }
-            : { label: 'scope', ok: true, detail: scoped ? `stored ${scoped.scope}` : 'stored local' });
+            ? { 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
@@ -971,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`. " +
@@ -1011,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,
@@ -1046,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)')
@@ -1101,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
@@ -1136,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
@@ -1184,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({
@@ -1204,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) {
@@ -1235,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')
@@ -1309,6 +1675,7 @@ function registerTaskCommands(browser) {
         .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) => {
@@ -1339,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) => {
@@ -1359,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({
@@ -1376,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({
@@ -1393,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);
@@ -1428,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')
@@ -1448,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.`);
         }
     });
@@ -1466,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);
@@ -1492,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')
@@ -1841,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')
@@ -1883,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) => {
@@ -1925,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.')
@@ -1989,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);
@@ -2008,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);
@@ -2027,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)
@@ -2061,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))
@@ -2112,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)
@@ -2136,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);
@@ -2166,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')
@@ -2196,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) => {
@@ -2228,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')
@@ -2273,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)')
@@ -2311,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)
@@ -2335,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')
@@ -2389,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) => {
@@ -2421,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))
@@ -2448,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 });
@@ -2464,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);