@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/agent-modes.js

@@ -14,9 +14,28 @@ import { resolveRunDefaults } from './run-defaults.js';
 export const MODE_DESCRIPTIONS = {
     plan: 'read-only investigation; no writes, no shell side-effects',
     edit: 'may edit files; prompts for shell / risky operations',
-    auto: 'smart classifier auto-approves safe ops, prompts for risky',
+    auto: 'more autonomy than edit; the exact policy is per-harness (see notes)',
     skip: 'bypass every permission prompt (dangerously-skip-permissions)',
 };
+/**
+ * What `auto` actually does, per harness. Two genuinely different mechanisms
+ * wear the same mode name, and conflating them is a safety error in both
+ * directions: telling a claude operator that auto never prompts invites an
+ * unattended run that stalls on a risky-operation gate, and telling a codex
+ * operator that auto prompts for risky work asserts a gate codex does not have.
+ * Absent entry = no extra note; the row's own text suffices.
+ */
+const AUTO_SEMANTICS = {
+    // Classifier-style: still escalates. --permission-mode auto / --autopilot.
+    claude: 'a smart classifier auto-approves safe operations and still prompts for risky ones.',
+    copilot: 'a smart classifier auto-approves safe operations and still prompts for risky ones.',
+    // Approvals off, sandbox kept: never escalates. A denied command just fails.
+    codex: 'approval_policy=never over the same sandbox as edit — it never prompts, and a sandbox-denied command fails instead of raising an approval request.',
+    muse: 'runs --disable-approval, which turns approvals off while keeping the sandbox — like codex, it never prompts and a denied command fails.',
+    // Native autonomy dial at its top setting.
+    droid: 'runs --auto high, droid\'s full-autonomy setting.',
+    kimi: "runs kimi's native --auto.",
+};
 /**
  * Build the permission-mode catalog for one harness.
  * `version` only affects the configured run.defaults lookup (modes themselves
@@ -42,6 +61,15 @@ export function getAgentModesCatalog(agent, version, cwd = process.cwd()) {
     if (unsupported.includes('auto')) {
         notes.push(`--mode auto degrades to edit on ${agent} (no native auto classifier).`);
     }
+    // MODE_DESCRIPTIONS is one flat Record<Mode, string> rendered for every agent,
+    // so it cannot name any single harness's mechanism without lying about the
+    // others: claude/copilot auto STILL PROMPTS for risky operations, while codex
+    // auto never prompts at all. The row states only what is true everywhere; the
+    // mechanism rides here, per harness.
+    const autoSemantics = AUTO_SEMANTICS[agent];
+    if (autoSemantics && supported.includes('auto')) {
+        notes.push(`${agent} --mode auto: ${autoSemantics}`);
+    }
     if (unsupported.includes('plan')) {
         notes.push(`--mode plan degrades to ${defaultMode} on ${agent} (no native read-only mode).`);
     }

package/dist/lib/agent-spec/agents.d.ts

@@ -552,9 +552,9 @@ export declare function resolveAgentName(input: string): AgentId | null;
 /** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;
 /**
- * Split a CLI-provided `<agent>[@<version>]` spec into its bare agent id and
- * optional exact version token, the same way `agents run` does
- * (commands/exec.ts parses its positional with a plain `split('@')`) — NOT the
+ * Split a CLI-provided `<agent>[@<version>][#<label>]` spec into its bare agent
+ * id, optional exact version token, and optional account label, the same way
+ * `agents run` does — NOT the
  * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
  * versions for read/diagnostic commands, not a single launch target. Returns an
  * error message rather than throwing so callers decide exit-vs-continue.
@@ -562,6 +562,7 @@ export declare function isAgentName(input: string): boolean;
 export declare function parseAgentVersionSpec(raw: string): {
     agent: AgentId;
     version?: string;
+    label?: string;
 } | {
     error: string;
 };

package/dist/lib/agent-spec/agents.js

@@ -298,7 +298,7 @@ export const AGENTS = {
         cloudProvider: 'codex',
         // Subagents: multi-agent plumbing since 0.117.0; custom agents as
         // ~/.codex/agents/*.toml (name, description, developer_instructions).
-        capabilities: { hooks: { since: '0.116.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: { since: '0.138.0' }, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: { since: '0.117.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'skip'], interactiveRepl: true },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, mcpHttp: true, mcpHeaders: false, allowlist: { since: '0.138.0' }, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' }, subagents: { since: '0.117.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: true, modes: ['plan', 'edit', 'auto', 'skip'], interactiveRepl: true },
     },
     gemini: {
         id: 'gemini',
@@ -1504,12 +1504,9 @@ const CREDENTIAL_FILE_SEGMENTS = {
     // Muse Code stores OAuth / API credentials at ~/.config/muse/auth.json
     // (or META_API_KEY in the environment, which is not a file).
     muse: [['.config', 'muse', 'auth.json']],
-    // Cursor's OAuth token — the login gate — is at $XDG_CONFIG_HOME/cursor/auth.json
-    // (~/.config/cursor/auth.json by default). cli-config.json holds only account
-    // metadata; the token file is what a real launch authenticates from, so a
-    // version home with no token of its own is genuinely logged out once runs pin
-    // XDG_CONFIG_HOME per home (see buildExecEnv).
-    cursor: [['.config', 'cursor', 'auth.json']],
+    // With AGENT_CLI_CREDENTIAL_STORE=file, Cursor stores both OAuth tokens at
+    // ~/.cursor/auth.json. cli-config.json holds account metadata only.
+    cursor: [['.cursor', 'auth.json']],
 };
 /** Whether an agent's credential file exists under a given home. */
 function credentialFileExistsUnder(agentId, home) {
@@ -2112,7 +2109,7 @@ export async function getAccountInfo(agentId, home) {
             case 'cursor': {
                 // Cursor CLI keeps account metadata in ~/.cursor/cli-config.json
                 // (authInfo: { email, userId, authId }) and its OAuth tokens SEPARATELY
-                // in ~/.config/cursor/auth.json ({ accessToken, refreshToken }). Presence
+                // in ~/.cursor/auth.json ({ accessToken, refreshToken }). Presence
                 // of an access token is the signed-in signal; email/ids come from
                 // cli-config. authId is the OAuth subject (e.g. "google-oauth2|<n>") — the
                 // same value the usage endpoint keys on (see getCursorUsageInfo).
@@ -2126,7 +2123,7 @@ export async function getAccountInfo(agentId, home) {
                     const accountId = normalizeIdentityPart(authInfo?.authId ?? authInfo?.userId);
                     if (!email && !accountId)
                         return { ...empty, lastActive };
-                    const authPath = resolveAccountCredentialPath(base, '.config', 'cursor', 'auth.json');
+                    const authPath = resolveAccountCredentialPath(base, '.cursor', 'auth.json');
                     let hasToken = false;
                     if (authPath) {
                         try {
@@ -2135,8 +2132,13 @@ export async function getAccountInfo(agentId, home) {
                         }
                         catch { /* unreadable token file */ }
                     }
+                    // cli-config survives logout and may describe a different keychain
+                    // account. Without this version's file token, its identity is stale
+                    // metadata rather than a usable managed login.
+                    if (!hasToken)
+                        return { ...empty, lastActive };
                     const accountKey = buildIdentityKey(agentId, [['user', accountId]]);
-                    return { ...empty, email, accountId, accountKey, signedIn: hasToken || !!email, lastActive };
+                    return { ...empty, email, accountId, accountKey, signedIn: true, lastActive };
                 }
                 catch { }
                 return { ...empty, lastActive };
@@ -3050,15 +3052,23 @@ export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
 /**
- * Split a CLI-provided `<agent>[@<version>]` spec into its bare agent id and
- * optional exact version token, the same way `agents run` does
- * (commands/exec.ts parses its positional with a plain `split('@')`) — NOT the
+ * Split a CLI-provided `<agent>[@<version>][#<label>]` spec into its bare agent
+ * id, optional exact version token, and optional account label, the same way
+ * `agents run` does — NOT the
  * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
  * versions for read/diagnostic commands, not a single launch target. Returns an
  * error message rather than throwing so callers decide exit-vs-continue.
  */
 export function parseAgentVersionSpec(raw) {
-    const parts = raw.split('@');
+    const labelParts = raw.split('#');
+    if (labelParts.length > 2) {
+        return { error: `Invalid agent spec '${raw}': at most one '#label' is allowed` };
+    }
+    const [versionSpec, rawLabel] = labelParts;
+    if (rawLabel !== undefined && (rawLabel === '' || !/^[a-zA-Z0-9][a-zA-Z0-9@._+-]*$/.test(rawLabel))) {
+        return { error: `Invalid account label '${rawLabel}' in '${raw}'` };
+    }
+    const parts = versionSpec.split('@');
     if (parts.length > 2) {
         return { error: `Invalid agent spec '${raw}': at most one '@version' is allowed` };
     }
@@ -3070,7 +3080,7 @@ export function parseAgentVersionSpec(raw) {
     if (rawVersion !== undefined && (rawVersion === '' || !VERSION_RE.test(rawVersion))) {
         return { error: `Invalid version '${rawVersion}' in '${raw}'` };
     }
-    return { agent, ...(rawVersion ? { version: rawVersion } : {}) };
+    return { agent, ...(rawVersion ? { version: rawVersion } : {}), ...(rawLabel ? { label: rawLabel } : {}) };
 }
 /**
  * Build the deprecation notice lines for an agent, or null if it isn't

package/dist/lib/analytics/mix-commands.d.ts

@@ -5,7 +5,7 @@
  * peer of `agents insights` with overlapping "analytics" meaning, so agents and
  * humans kept picking the wrong verb. The cheap counter path (sessions index +
  * usage.db) still exists — it is now `agents insights mix` and the recipe
- * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ * subcommands below. Latency stays on `agents perf`; quota on `agents view`.
  *
  * Former top-level `agents trends` is gone. The nested spelling
  * `agents insights trends` is an alias of `agents insights mix`.

package/dist/lib/analytics/mix-commands.js

@@ -5,7 +5,7 @@
  * peer of `agents insights` with overlapping "analytics" meaning, so agents and
  * humans kept picking the wrong verb. The cheap counter path (sessions index +
  * usage.db) still exists — it is now `agents insights mix` and the recipe
- * subcommands below. Latency stays on `agents perf`; quota on `agents usage`.
+ * subcommands below. Latency stays on `agents perf`; quota on `agents view`.
  *
  * Former top-level `agents trends` is gone. The nested spelling
  * `agents insights trends` is an alias of `agents insights mix`.
@@ -97,7 +97,7 @@ export function registerMixCommands(parent) {
       Session recipes read sessions.db; resource recipes read ~/.agents/.history/analytics/usage.db.
       Empty recipes are skipped on the default mix board.
       This is the cheap counter path. Behavioural report (transcript content, account split)
-      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents usage\`.
+      is bare \`agents insights\`. Latency is \`agents perf\`; quota is \`agents view\`.
       Skill/slash-command popularity is \`agents sessions stats\`.
     `,
     });

package/dist/lib/auth-health.d.ts

@@ -148,13 +148,21 @@ export declare function mergeAuthHealthEntries(current: Record<string, AuthHealt
 export declare function writeAuthHealthEntries(entries: Record<string, AuthHealth>): void;
 /**
  * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
- * hits the provider; for everyone else it reports a best-effort local verdict
- * (`unverified` when a credential is present, `unconfigured` otherwise) — never
- * masquerading as `live`.
+ * hits the provider — unless the account's usage cache already holds a fresh
+ * successful fetch, which is the same authenticated request and proves the
+ * token live without spending a second one (RUSH-3036). For everyone else it
+ * reports a best-effort local verdict (`unverified` when a credential is
+ * present, `unconfigured` otherwise) — never masquerading as `live`.
  */
 export declare function probeAuthHealth(agent: AgentId, home: string | undefined, opts?: {
     cliVersion?: string | null;
     info?: AccountInfo | null;
+    /**
+     * Skip the derived-from-usage shortcut and fire a real network probe
+     * (RUSH-3036). Set by `agents devices ping [--strict]`, whose contract is
+     * a genuinely live request that surfaces `revoked` immediately.
+     */
+    forceLive?: boolean;
 }): Promise<AuthHealth>;
 /** One probed install on a host. */
 export interface AuthProbeRow {
@@ -215,6 +223,8 @@ export declare function groupFleetAuthInstalls<T extends FleetAuthInstall>(insta
 export declare function probeLocalFleetAuth(opts?: {
     cliVersion?: string | null;
     agents?: readonly AgentId[];
+    /** Fire real network probes even when fresh usage evidence exists (RUSH-3036) — the `devices ping [--strict]` contract. */
+    forceLive?: boolean;
 }): Promise<AuthProbeRow[]>;
 /** Persist a host's probed rows into the cache (keyed by host+agent+version). */
 export declare function writeFleetAuthRows(host: string, rows: AuthProbeRow[]): void;

package/dist/lib/auth-health.js

@@ -20,7 +20,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
 import { getCacheDir } from './state.js';
-import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, } from './accounting/usage.js';
+import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, readClaudeUsageCache, } from './accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 /** Agents with a live network probe wired up today. The rest are best-effort. */
@@ -294,22 +294,64 @@ export function writeAuthHealthEntries(entries) {
 // ---------------------------------------------------------------------------
 // The probe (writer side)
 // ---------------------------------------------------------------------------
+/**
+ * A usage snapshot this recent is live proof the account's shared setup-token
+ * works: the snapshot only exists because an authenticated `/oauth/usage`
+ * request succeeded. Matches the periodic tick's own probe window
+ * (AUTH_PROBE_MAX_AGE_MS in daemon-ticks.ts — not imported to avoid a cycle;
+ * a drift here only widens/narrows evidence freshness, never correctness).
+ */
+const FRESH_USAGE_VERDICT_MAX_AGE_MS = 20 * 60_000;
+/**
+ * A `live` verdict derived from the account's usage cache instead of a second
+ * network request (RUSH-3036). The auth probe and the usage fetch hit the SAME
+ * rate-limited endpoint with the SAME fleet-shared setup-token, so a fresh
+ * successful usage snapshot already proves everything the probe would: paying a
+ * second request per account per box was half the fleet's endpoint load.
+ *
+ * Two guards keep the evidence honest (both review findings on the first cut):
+ * the caller must assert this box holds a LOCAL credential for the account
+ * (`signedIn`) — a fleet-imported snapshot proves the shared token works, not
+ * that THIS box can authenticate, so an unsigned home never derives `live`;
+ * and a `forceLive` caller (`agents devices ping --strict`) skips derivation
+ * entirely, because its contract is a real request that can surface `revoked`
+ * within seconds, not minutes. Returns null when there is no admissible fresh
+ * evidence — the caller then live-probes as before.
+ */
+function verdictFromFreshUsage(usageKey, signedIn, now) {
+    if (!usageKey || !signedIn)
+        return null;
+    const snapshot = readClaudeUsageCache(usageKey);
+    const capturedAt = snapshot?.capturedAt?.getTime();
+    if (!capturedAt || now - capturedAt >= FRESH_USAGE_VERDICT_MAX_AGE_MS)
+        return null;
+    const ageMin = Math.max(1, Math.round((now - capturedAt) / 60_000));
+    return { verdict: 'live', checkedAt: now, detail: `token proven live by a usage fetch ${ageMin}m ago` };
+}
 /**
  * Complete a live auth probe for one (agent, home). For claude/kimi/droid this
- * hits the provider; for everyone else it reports a best-effort local verdict
- * (`unverified` when a credential is present, `unconfigured` otherwise) — never
- * masquerading as `live`.
+ * hits the provider — unless the account's usage cache already holds a fresh
+ * successful fetch, which is the same authenticated request and proves the
+ * token live without spending a second one (RUSH-3036). For everyone else it
+ * reports a best-effort local verdict (`unverified` when a credential is
+ * present, `unconfigured` otherwise) — never masquerading as `live`.
  */
 export async function probeAuthHealth(agent, home, opts) {
     const checkedAt = Date.now();
     if (LIVE_PROBE_AGENTS.has(agent)) {
+        const usageScope = opts?.info?.usageKey ?? null;
+        if (opts?.forceLive !== true) {
+            const derived = verdictFromFreshUsage(usageScope, opts?.info?.signedIn === true, checkedAt);
+            if (derived)
+                return derived;
+        }
         let probe;
         if (agent === 'claude')
-            probe = await probeClaudeStatus(home, opts?.cliVersion);
+            probe = await probeClaudeStatus(home, opts?.cliVersion, usageScope);
         else if (agent === 'kimi')
-            probe = await probeKimiStatus(home);
+            probe = await probeKimiStatus(home, usageScope);
         else
-            probe = await probeDroidStatus(home);
+            probe = await probeDroidStatus(home, usageScope);
         return { verdict: verdictFromProbe(probe), checkedAt, detail: probeDetail(probe) };
     }
     const info = opts?.info !== undefined ? opts.info : await getAccountInfo(agent, home).catch(() => null);
@@ -384,7 +426,7 @@ export async function probeLocalFleetAuth(opts) {
     // accounts, so no same-account concurrency is left to trip the throttle.
     const perGroup = await Promise.all(groupFleetAuthInstalls(installs, (inst) => LIVE_PROBE_AGENTS.has(inst.agent)).map(async (group) => {
         const rep = group.probe;
-        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info });
+        const health = await probeAuthHealth(rep.agent, rep.home, { cliVersion: opts?.cliVersion, info: rep.info, forceLive: opts?.forceLive });
         health.account = authAccountLabel(rep.info);
         if (health.verdict === 'unconfigured')
             return [];

package/dist/lib/browser/devices.d.ts

@@ -13,3 +13,22 @@ export declare const DEFAULT_VIEWPORT: {
 export declare const DEVICES: Record<string, DeviceDescriptor>;
 export declare function getDevice(name: string): DeviceDescriptor | undefined;
 export declare function listDevices(): string[];
+/**
+ * Parse a `--window WxH` value. Returns null when the value is malformed, so
+ * callers emit their own actionable error.
+ *
+ * Shared by `profiles create` and `profiles edit` — one regex, one test, no
+ * drift between the two surfaces.
+ */
+export declare function parseWindowSize(raw: string): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Parse a `--position X,Y` value. Negative coordinates are valid — a window may
+ * sit on a display left of or above the primary one.
+ */
+export declare function parseWindowPosition(raw: string): {
+    x: number;
+    y: number;
+} | null;

package/dist/lib/browser/devices.js

@@ -36,3 +36,26 @@ export function getDevice(name) {
 export function listDevices() {
     return Object.keys(DEVICES);
 }
+/**
+ * Parse a `--window WxH` value. Returns null when the value is malformed, so
+ * callers emit their own actionable error.
+ *
+ * Shared by `profiles create` and `profiles edit` — one regex, one test, no
+ * drift between the two surfaces.
+ */
+export function parseWindowSize(raw) {
+    const m = String(raw).match(/^(\d+)x(\d+)$/);
+    if (!m)
+        return null;
+    return { width: parseInt(m[1], 10), height: parseInt(m[2], 10) };
+}
+/**
+ * Parse a `--position X,Y` value. Negative coordinates are valid — a window may
+ * sit on a display left of or above the primary one.
+ */
+export function parseWindowPosition(raw) {
+    const m = String(raw).match(/^(-?\d+),(-?\d+)$/);
+    if (!m)
+        return null;
+    return { x: parseInt(m[1], 10), y: parseInt(m[2], 10) };
+}

package/dist/lib/browser/drivers/ssh.d.ts

@@ -16,13 +16,27 @@ export interface SSHConnection {
  * strings differ (no `&` backgrounding, no `lsof`, `.exe` instead of `.app`).
  */
 export type RemoteOs = 'windows' | 'posix';
+export interface SSHConnectOptions {
+    /**
+     * Attach to a browser another device already declared (identity-bearing or
+     * a fungible name we don't declare here). Do not launch a fresh remote
+     * chrome-data, and do not kill that browser when the tunnel closes — it
+     * holds the logins the caller is trying to reach.
+     */
+    persistRemote?: boolean;
+}
+/** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
+export declare function persistRemoteLifecycle(persistRemote: boolean): {
+    launchRemote: boolean;
+    killOnCleanup: boolean;
+};
 export declare function connectSSH(endpoint: string, profile: BrowserProfile, 
 /**
- * Runtime key (`<profile>@<endpoint>`) this connection is stored under. It
+ * Runtime key (`<profile>@<device>`) this connection is stored under. It
  * keys the tunnel's runtime record; `profile.name` is the bare, user-facing
  * name and appears only in messages (RUSH-2709).
  */
-key: ConnectionKey): Promise<SSHConnection>;
+key: ConnectionKey, opts?: SSHConnectOptions): Promise<SSHConnection>;
 /**
  * Wrap a PowerShell script as a `-EncodedCommand` invocation. Base64 of the
  * UTF-16LE bytes is a single quote-free token, so it rides through Node spawn

package/dist/lib/browser/drivers/ssh.js

@@ -13,13 +13,19 @@ export { shellQuote };
 // driver's original foreground, stderr-captured behavior exactly.
 import { startSSHTunnel } from '../../computer/ssh-tunnel.js';
 import { encodePwshBase64 } from '../../pwsh.js';
+/** Lifecycle for a registry-driven tunnel vs a profile the daemon launched. */
+export function persistRemoteLifecycle(persistRemote) {
+    return persistRemote
+        ? { launchRemote: false, killOnCleanup: false }
+        : { launchRemote: true, killOnCleanup: true };
+}
 export async function connectSSH(endpoint, profile, 
 /**
- * Runtime key (`<profile>@<endpoint>`) this connection is stored under. It
+ * Runtime key (`<profile>@<device>`) this connection is stored under. It
  * keys the tunnel's runtime record; `profile.name` is the bare, user-facing
  * name and appears only in messages (RUSH-2709).
  */
-key) {
+key, opts = {}) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
         throw new Error(`Invalid SSH endpoint: ${endpoint}`);
@@ -59,7 +65,14 @@ key) {
     // (the launch backgrounds/WMI-spawns regardless), so this does not spuriously
     // fail the reconnect path — only genuine launch failures reach the caller
     // instead of being swallowed and mis-reported later as a tunnel timeout.
-    await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
+    //
+    // persistRemote skips the launch: launching would mint a logged-out
+    // `--user-data-dir=/tmp/agents-browser-N` under a name that means a
+    // credentialed browser on the declaring device.
+    const lifecycle = persistRemoteLifecycle(Boolean(opts.persistRemote));
+    if (lifecycle.launchRemote) {
+        await ensureRemoteBrowser(user, host, profile.browser, remotePort, remoteOs, profile.binary);
+    }
     let tunnel;
     if (occupant) {
         // Reuse the existing tunnel rather than spawning a duplicate.
@@ -78,7 +91,19 @@ key) {
         tunnel.kill();
         throw new Error(`SSH tunnel failed to establish to ${host}`);
     }
-    const { wsUrl, browser } = await discoverBrowserWsUrl(localPort, 'localhost', profile.name);
+    let wsUrl;
+    let browser;
+    try {
+        ({ wsUrl, browser } = await discoverBrowserWsUrl(localPort, 'localhost', profile.name));
+    }
+    catch (err) {
+        tunnel.kill();
+        if (opts.persistRemote) {
+            const why = err instanceof Error ? err.message : String(err);
+            throw new Error(`Browser profile "${profile.name}" is declared on ${host}, but nothing is speaking CDP on port ${remotePort}: ${why}`);
+        }
+        throw err;
+    }
     try {
         verifyBrowserIdentity(browser, profile.browser, remotePort, host);
     }
@@ -108,11 +133,13 @@ key) {
         pid: tunnelPid,
         cleanup: () => {
             cdp.close();
-            // Kill the remote browser BEFORE tearing down the tunnel. It runs on a
-            // separate ssh connection (independent of the tunnel we're about to
-            // kill), so tunnel teardown can't cut it off. Fire-and-forget — cleanup
-            // stays synchronous, and killRemoteBrowser never rejects.
-            killRemoteBrowser(user, host, remoteOs, remotePort).catch(() => { });
+            // Kill the remote browser BEFORE tearing down the tunnel — but only
+            // when we launched it. persistRemote is an attach to someone else's
+            // declared browser; killing it would drop the logins the caller came
+            // for. Fire-and-forget — cleanup stays synchronous.
+            if (lifecycle.killOnCleanup) {
+                killRemoteBrowser(user, host, remoteOs, remotePort).catch(() => { });
+            }
             tunnel.kill();
             clearProfileRuntime(key);
         },

package/dist/lib/browser/ipc.d.ts

@@ -96,7 +96,7 @@ export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOpt
  * Fill actor / launchId / sessionId from the calling process when the request
  * left them blank. Explicit values on the request always win.
  */
-export declare function stampCallerIdentity(request: IPCRequest): IPCRequest;
+export declare function stampCallerIdentity(request: IPCRequest, env?: NodeJS.ProcessEnv): IPCRequest;
 /**
  * Open one connection that can serve many browser operations. This uses the
  * same daemon readiness and version-reconciliation path as sendIPCRequest;

package/dist/lib/browser/ipc.js

@@ -8,6 +8,7 @@ import { startDaemon, stopDaemon } from '../daemon/daemon.js';
 import { getCliVersion } from '../version.js';
 import { compareVersions } from '../agent-spec/primitives.js';
 import { getDaemonLogPath } from '../daemon/daemon.js';
+import { isFleetRemoteInvocation } from './remote-control.js';
 import { resolveCallerIdentity } from './caller-identity.js';
 import { actionable } from './service.js';
 /**
@@ -382,6 +383,7 @@ export class BrowserIPCServer {
                 actor: request.actor,
                 launchId: request.launchId,
                 sessionId: request.sessionId,
+                fleetRemote: request.fleetRemote,
                 createIfMissing,
                 title: request.title,
                 url: request.url,
@@ -396,6 +398,9 @@ export class BrowserIPCServer {
                 };
             }
             request.task = resolved.task.name;
+            if (resolved.created && resolved.picked) {
+                request.picked = resolved.picked;
+            }
             return undefined;
         }
         catch (err) {
@@ -421,6 +426,22 @@ export class BrowserIPCServer {
             case 'version': {
                 return { ok: true, version: getCliVersion() };
             }
+            case 'show': {
+                // Task-less by design — see BrowserService.showUrl. Absent from both
+                // PAGE_CREATE_VERBS and PAGE_RESOLVE_VERBS, so bindTask never ran above
+                // and this request carries no task.
+                if (!request.url) {
+                    return { ok: false, error: actionable('URL required.', 'Next: agents browser navigate <url>') };
+                }
+                if (!request.profile) {
+                    return { ok: false, error: actionable('Profile required.', 'Next: agents browser profiles list') };
+                }
+                const shown = await this.service.showUrl(request.profile, request.url, {
+                    fleetRemote: request.fleetRemote,
+                    actor: request.actor,
+                });
+                return { ok: true, tabId: shown.tabId, message: shown.picked };
+            }
             case 'start': {
                 if (!request.profile) {
                     return { ok: false, error: actionable('Profile required.', 'Next: agents browser profiles list') };
@@ -434,6 +455,7 @@ export class BrowserIPCServer {
                     actor: request.actor,
                     launchId: request.launchId,
                     sessionId: request.sessionId,
+                    fleetRemote: request.fleetRemote,
                     title: request.title,
                 });
                 return {
@@ -442,10 +464,11 @@ export class BrowserIPCServer {
                     tabId: result.tabId,
                     windowTargetId: result.windowId,
                     skill: result.skill,
+                    message: result.picked,
                 };
             }
             // The out-of-process seam onto the abandoned-task reaper: the daemon
-            // owns the live BrowserService, so a CLI verb (`agents browser gc`) can
+            // owns the live BrowserService, so a CLI verb (`agents browser prune`) can
             // only reach `reapAbandoned` through IPC. The daemon's own periodic tick
             // calls the service method directly.
             case 'gc': {
@@ -514,7 +537,8 @@ export class BrowserIPCServer {
                     };
                 }
                 const result = await this.service.navigate(request.task, request.url, request.profile);
-                return { ok: true, tabId: result.tabId, task: request.task };
+                const picked = request.picked;
+                return { ok: true, tabId: result.tabId, task: request.task, message: picked };
             }
             case 'tab-add': {
                 if (!request.task || !request.url) {
@@ -855,15 +879,22 @@ export async function sendIPCRequest(request, opts = {}) {
  * Fill actor / launchId / sessionId from the calling process when the request
  * left them blank. Explicit values on the request always win.
  */
-export function stampCallerIdentity(request) {
-    if (request.actor && request.launchId && request.sessionId)
-        return request;
+export function stampCallerIdentity(request, env = process.env) {
+    // The consent marker is stamped FIRST, above the identity early-return: a
+    // request that already carries a full identity (every streamed request does)
+    // would otherwise skip stamping entirely and reach the daemon unmarked.
+    // OR-ed, never overwritten — a client may assert the marker but must not be
+    // able to clear one this environment sets.
+    const fleetRemote = isFleetRemoteInvocation(env) || request.fleetRemote === true;
+    const marked = request.fleetRemote === fleetRemote ? request : { ...request, fleetRemote };
+    if (marked.actor && marked.launchId && marked.sessionId)
+        return marked;
     const id = resolveCallerIdentity();
     return {
-        ...request,
-        actor: request.actor ?? id.actor,
-        launchId: request.launchId ?? id.launchId,
-        sessionId: request.sessionId ?? id.sessionId,
+        ...marked,
+        actor: marked.actor ?? id.actor,
+        launchId: marked.launchId ?? id.launchId,
+        sessionId: marked.sessionId ?? id.sessionId,
     };
 }
 /**