@phnx-labs/agents-cli 1.18.4 → 1.18.5

package/dist/commands/factory.js

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { homedir } from 'os';
 import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
+import { insertTask } from '../lib/cloud/store.js';
 const FACTORY_URL = process.env.FACTORY_FLOOR_URL ?? 'https://agents.427yosemite.com';
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
@@ -63,9 +64,20 @@ Examples:
             console.log(JSON.stringify(result, null, 2));
             return;
         }
+        // Register locally so `agents cloud logs <id>` can find it.
+        const now = new Date().toISOString();
+        insertTask({
+            id: result.cloud_execution_id,
+            provider: 'rush',
+            status: 'queued',
+            agent: 'claude',
+            prompt: result.linear_identifier,
+            createdAt: now,
+            updatedAt: now,
+        });
         console.log(chalk.green(`Submitted ${result.linear_identifier} (${result.label})`));
         console.log(`  ticket       ${result.ticket_id}`);
         console.log(`  execution    ${result.cloud_execution_id}`);
-        console.log(`  tail output  agents cloud tail ${result.cloud_execution_id}`);
+        console.log(`  tail output  agents cloud logs ${result.cloud_execution_id}`);
     });
 }

package/dist/commands/rules.js

@@ -41,6 +41,20 @@ When to use:
   - Team onboarding: share rules via 'agents rules add gh:team/standards'
   - Project setup: add project-specific rules with '--scope project'
   - Version testing: install different rule sets per version to A/B test approaches
+
+Project rules & @-imports:
+  Project rules live in <repo>/.agents/rules/. On every agent launch, the shim compiles
+  them into <repo>/AGENTS.md (with CLAUDE.md, GEMINI.md, .cursorrules symlinked to it).
+  A hand-authored AGENTS.md is preserved — the compile pipeline only overwrites files
+  it owns (those starting with the auto-compile header). Delete the file to migrate.
+
+  @path imports inside AGENTS.md/CLAUDE.md are resolved at session start by the agent
+  itself, not by agents-cli. Support is per-agent:
+    Inlined natively:  claude, gemini
+    Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose, roo
+
+  For rules that need to work across all agents, inline the content rather than using
+  @-imports — the second group will load '@path/to/file.md' as a literal string.
 `);
     rulesCmd
         .command('list [agent]')

package/dist/commands/secrets.js

@@ -7,7 +7,7 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
-import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
+import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { registerCommandGroups } from '../lib/help.js';
@@ -314,7 +314,7 @@ function countExpiringSoon(meta) {
 export function registerSecretsCommands(program) {
     const cmd = program
         .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain (with optional iCloud sync). Inject into agents via `agents run --secrets <name>`.')
+        .description('Named bundles of env variables backed by macOS Keychain (iCloud-synced by default). Inject into agents via `agents run --secrets <name>`.')
         .hook('preAction', () => { migrateLegacyBundles(); })
         .addHelpText('after', `
 Workflow:
@@ -323,16 +323,24 @@ Workflow:
   run with --secrets <name>. Keychain-backed values never touch disk in
   plaintext.
 
-  Pass --icloud-sync at create time to store values in the iCloud-synced
-  keychain so they appear automatically on your other Macs (same iCloud
-  account, iCloud Keychain enabled). Without the flag, values are device-local.
+  New bundles store values in the iCloud-synced keychain by default so they
+  appear automatically on your other Macs (same iCloud account, iCloud
+  Keychain enabled). Pass --no-icloud-sync at create time to keep values
+  device-local instead.
 
 Examples:
-  # Create a bundle for production credentials
+  # Create a bundle for production credentials (iCloud-synced by default)
   agents secrets create prod --description "Production keys for the api stack"
 
-  # Create a bundle that syncs to your other Macs via iCloud Keychain
-  agents secrets create npm-tokens --icloud-sync
+  # Create a bundle that never leaves this Mac
+  agents secrets create local-only --no-icloud-sync
+
+  # Rename a bundle (moves metadata + every keychain value)
+  agents secrets rename prod production
+
+  # Edit the description of an existing bundle
+  agents secrets describe prod "Production keys for the api stack"
+  agents secrets describe prod --clear
 
   # Add a keychain-backed secret (prompts for the value)
   agents secrets add prod STRIPE_API_KEY
@@ -387,7 +395,7 @@ Examples:
   agents secrets generate 32 --hex
 `);
     registerCommandGroups(cmd, [
-        { title: 'Bundle commands', names: ['list', 'view', 'create', 'delete'] },
+        { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
         { title: 'Utilities', names: ['exec', 'generate'] },
     ]);
@@ -484,7 +492,7 @@ Examples:
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--icloud-sync', 'Store keychain values in iCloud Keychain so they sync across your Macs (requires Xcode CLT)')
+        .option('--no-icloud-sync', 'Store keychain values device-local instead of syncing them via iCloud Keychain')
         .option('--force', 'Overwrite an existing bundle')
         .action(async (name, opts) => {
         try {
@@ -498,7 +506,7 @@ Examples:
                 name: resolvedName,
                 description: opts.description,
                 allow_exec: opts.allowExec,
-                icloud_sync: opts.icloudSync,
+                icloud_sync: opts.icloudSync !== false,
                 vars: {},
             };
             writeBundle(bundle);
@@ -512,6 +520,53 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('rename <old> <new>')
+        .alias('mv')
+        .description('Rename a bundle. Moves the metadata and every keychain-backed value to the new name.')
+        .option('--force', 'Overwrite the destination bundle if it already exists (purges its keychain items first)')
+        .action((oldName, newName, opts) => {
+        try {
+            renameBundle(oldName, newName, { force: opts.force });
+            console.log(chalk.green(`Bundle '${oldName}' renamed to '${newName}'.`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+    cmd
+        .command('describe <name> [text...]')
+        .description('Update the description of a bundle. Pass --clear to remove it.')
+        .option('--clear', 'Remove the existing description')
+        .action((name, textParts, opts) => {
+        try {
+            const bundle = readBundle(name);
+            const text = textParts.join(' ').trim();
+            if (opts.clear) {
+                if (text) {
+                    console.error(chalk.red('Pass either description text or --clear, not both.'));
+                    process.exit(1);
+                }
+                bundle.description = undefined;
+            }
+            else {
+                if (!text) {
+                    console.error(chalk.red('Description text is required. Pass it as an argument or use --clear.'));
+                    process.exit(1);
+                }
+                bundle.description = text;
+            }
+            writeBundle(bundle);
+            console.log(chalk.green(opts.clear
+                ? `Bundle '${name}' description cleared.`
+                : `Bundle '${name}' description updated.`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     cmd
         .command('add [bundle] [key]')
         .description('Add a variable to a bundle. Defaults to keychain-backed; pass --value for literal, --env/--file/--exec for refs.')

package/dist/lib/browser/cdp.js

@@ -14,7 +14,13 @@ export class CDPClient {
     }
     async send(method, params, sessionId) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
-            throw new Error('CDP connection not open');
+            // Reached when the underlying browser was killed externally between
+            // the daemon establishing the connection and a CDP call going out.
+            // The service-layer healthcheck normally catches this on the next
+            // `start`, so seeing this in the wild means a request landed against
+            // an in-flight conn that just died — tell the user how to recover.
+            throw new Error('CDP connection not open — the browser was likely closed externally. ' +
+                'Run `agents browser stop --profile <name>` (or restart the daemon) and try again.');
         }
         const id = ++this.messageId;
         const message = sessionId

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

@@ -6,7 +6,7 @@ export interface LaunchResult {
     port: number;
     wsUrl: string;
 }
-export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string): Promise<LaunchResult>;
+export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string, isElectron?: boolean): Promise<LaunchResult>;
 export declare function attachToChrome(port: number): Promise<string>;
 export declare function killChrome(pid: number): void;
 export declare function getRunningChromeInfo(profileName: string): {

package/dist/lib/browser/chrome.js

@@ -5,6 +5,7 @@ import * as os from 'os';
 import { getProfileRuntimeDir } from './profiles.js';
 import { discoverBrowserWsUrl } from './cdp.js';
 import { readBundle, resolveBundleEnv, bundleExists } from '../secrets/bundles.js';
+import { writeProfileRuntime, readProfileRuntime } from './runtime-state.js';
 const BROWSER_PATHS = {
     darwin: {
         chrome: [
@@ -64,11 +65,27 @@ export function findBrowserPath(browserType, customBinary) {
     }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
-export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary) {
+export async function launchBrowser(profileName, browserType, port, options = {}, secrets, customBinary, 
+// `electron: true` distinguishes Notion / VS Code-style apps from
+// regular Chrome — purely informational, stored in meta.json so the
+// orphan reaper and `agents browser status` can label processes.
+isElectron = false) {
     const browserPath = findBrowserPath(browserType, customBinary);
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });
+    // First-launch seed: stamp the user-data-dir's Default/Preferences with
+    // the agents-cli profile name so Chromium's UI shows "<profile>" instead
+    // of its default "Person 1". Done only when the file doesn't exist —
+    // subsequent launches inherit whatever Chrome wrote in the meantime.
+    seedDefaultProfileName(userDataDir, profileName);
+    // Chromium on macOS coordinates instances via the SingletonLock file
+    // *inside* each user-data-dir. Direct binary spawn with a fresh
+    // --user-data-dir creates a fully independent process — the user's
+    // normal browser (running under their default user-data-dir) and our
+    // sandboxed one coexist as two real processes. The macOS Dock collapses
+    // them into one icon per .app bundle, which makes it look like a single
+    // instance, but `ps -ww` will show both.
     const viewport = options.viewport ?? { width: 1512, height: 982 };
     const args = [
         `--remote-debugging-port=${port}`,
@@ -77,6 +94,12 @@ export async function launchBrowser(profileName, browserType, port, options = {}
         '--disable-background-timer-throttling',
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
+        // First-run + default-browser modals block automation: when targetFilter
+        // matches by URL, the onboarding page (`chrome://welcome/`) isn't a
+        // match and start fails with "no page target". Suppress them.
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-features=DefaultBrowserSetting,ChromeWhatsNewUI',
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -102,8 +125,13 @@ export async function launchBrowser(profileName, browserType, port, options = {}
     });
     child.unref();
     const pid = child.pid;
-    fs.writeFileSync(path.join(runtimeDir, 'pid'), String(pid));
-    fs.writeFileSync(path.join(runtimeDir, 'port'), String(port));
+    writeProfileRuntime(profileName, {
+        pid,
+        port,
+        command: path.basename(browserPath),
+        userDataDir,
+        kind: isElectron ? 'electron' : 'browser',
+    });
     let wsUrl = null;
     for (let i = 0; i < 30; i++) {
         await sleep(200);
@@ -134,33 +162,31 @@ export function killChrome(pid) {
     }
 }
 export function getRunningChromeInfo(profileName) {
-    const runtimeDir = getProfileRuntimeDir(profileName);
-    const pidFile = path.join(runtimeDir, 'pid');
-    const portFile = path.join(runtimeDir, 'port');
-    if (!fs.existsSync(pidFile) || !fs.existsSync(portFile)) {
-        return null;
-    }
-    const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
-    const port = parseInt(fs.readFileSync(portFile, 'utf-8').trim(), 10);
-    if (!isProcessRunning(pid)) {
-        fs.unlinkSync(pidFile);
-        fs.unlinkSync(portFile);
+    // Delegate to runtime-state, which auto-cleans stale files and verifies
+    // the live pid still runs the command we recorded — so a recycled pid
+    // doesn't masquerade as our browser.
+    const rt = readProfileRuntime(profileName);
+    if (!rt)
         return null;
-    }
-    return { pid, port };
+    return { pid: rt.pid, port: rt.port };
 }
-function isProcessRunning(pid) {
+/**
+ * Stamp `<userDataDir>/Default/Preferences` with our profile name so
+ * Chrome's UI labels the window with the agents-cli name rather than the
+ * default "Person 1". Only writes when the file is absent (first launch).
+ * Best-effort: any I/O hiccup is silently ignored; missing the rename is
+ * cosmetic, not functional.
+ */
+function seedDefaultProfileName(userDataDir, profileName) {
+    const defaultDir = path.join(userDataDir, 'Default');
+    const prefsPath = path.join(defaultDir, 'Preferences');
+    if (fs.existsSync(prefsPath))
+        return;
     try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        // EPERM means the process exists but we lack permission to signal it —
-        // treat as alive. ESRCH means the process does not exist.
-        if (err && err.code === 'EPERM')
-            return true;
-        return false;
+        fs.mkdirSync(defaultDir, { recursive: true });
+        fs.writeFileSync(prefsPath, JSON.stringify({ profile: { name: profileName } }));
     }
+    catch { /* not critical */ }
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

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

@@ -1,11 +1,38 @@
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { launchBrowser, getPortOccupant } from '../chrome.js';
+import { parseEndpointUrl } from '../profiles.js';
+/**
+ * Local-port listeners we refuse to attach through. These forward CDP traffic
+ * to a remote host — silently using them would let a `cdp://127.0.0.1:N`
+ * profile drive a browser on a different machine without the caller realizing.
+ */
+const TUNNEL_PROCESS_NAMES = new Set(['ssh', 'autossh', 'mosh-client', 'socat']);
+function isTunnelProcess(command) {
+    return TUNNEL_PROCESS_NAMES.has(command.toLowerCase());
+}
 export async function connectLocal(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'cdp:') {
         throw new Error(`Invalid local endpoint: ${endpoint}`);
     }
-    const port = parseInt(url.port, 10) || 9222;
+    // Share the parser with the SSH driver and the collision-detection code
+    // path so `cdp://host:N` and `cdp://host?port=N` behave identically.
+    const parsed = parseEndpointUrl(endpoint);
+    const port = parsed?.port ?? 9222;
+    // Refuse to attach through an SSH tunnel before we even try to speak CDP.
+    // `verifyBrowserIdentity` only inspects what comes back over the wire — it
+    // can't tell whether the browser actually lives on this machine or on the
+    // far end of an `ssh -L` tunnel. A stale tunnel from a prior session
+    // (common when an SSH-driven profile is deleted before the daemon exits)
+    // will silently hijack any "local" profile bound to the same port.
+    const preOccupant = getPortOccupant(port);
+    if (preOccupant && isTunnelProcess(preOccupant.command)) {
+        throw new Error(`Port ${port} is held by ${preOccupant.command} (pid ${preOccupant.pid}), an SSH ` +
+            `tunnel forwarding to a remote host. Profile "${profile.name}" is configured as ` +
+            `local (${endpoint}) but traffic would round-trip to another machine. Either kill ` +
+            `the tunnel (\`kill ${preOccupant.pid}\`) and retry, or switch the profile to an ` +
+            `ssh:// endpoint to drive the remote browser explicitly.`);
+    }
     try {
         const { wsUrl, browser } = await discoverBrowserWsUrl(port);
         verifyBrowserIdentity(browser, profile.browser, port);
@@ -30,7 +57,7 @@ export async function connectLocal(endpoint, profile) {
         }
         const newPort = port;
         const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
-        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary);
+        const { pid, wsUrl } = await launchBrowser(profile.name, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary, profile.electron === true);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port: newPort, pid };

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

@@ -1,23 +1,56 @@
-import { spawn } from 'child_process';
+import { spawn, execSync } from 'child_process';
 import * as net from 'net';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
-import { allocatePort } from '../chrome.js';
+import { getPortOccupant } from '../chrome.js';
+import { parseEndpointUrl } from '../profiles.js';
+import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
         throw new Error(`Invalid SSH endpoint: ${endpoint}`);
     }
     const user = url.username || process.env.USER || 'root';
-    const host = url.hostname;
-    const remotePort = url.port ? parseInt(url.port, 10) : 9222;
-    const localPort = allocatePort();
+    // Use the shared parser so the documented `ssh://host?port=N` form works
+    // identically to `ssh://host:N`. Previously `url.port` alone meant every
+    // `?port=`-style profile silently fell back to 9222.
+    const parsed = parseEndpointUrl(endpoint);
+    if (!parsed) {
+        throw new Error(`Could not extract host:port from SSH endpoint: ${endpoint}`);
+    }
+    const host = parsed.host;
+    const remotePort = parsed.port;
+    // Bind the tunnel to the SAME local port the user configured. Using an
+    // allocated port instead made `status` print confusing rows like
+    // `port 9200 (configured 10005)` and made it impossible to predict which
+    // local port a profile would land on. Now `ssh://host?port=N` => local N.
+    const localPort = remotePort;
+    // Preflight: if the local port is busy with something that isn't our
+    // own SSH tunnel for this very target, bail with a clear error. Letting
+    // ssh -L race ahead would either silently succeed (binding to a second
+    // port via fail-safe) or fail with cryptic stderr.
+    const occupant = getPortOccupant(localPort);
+    if (occupant && !isOwnTunnel(occupant.pid, host, remotePort)) {
+        throw new Error(`Local port ${localPort} (needed for SSH tunnel to ${host}:${remotePort}) ` +
+            `is already in use by ${occupant.command} (pid ${occupant.pid}). ` +
+            `Either kill that process (\`kill ${occupant.pid}\`) or change the profile's port.`);
+    }
     try {
         await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
     }
     catch {
         // Browser may already be running, continue
     }
-    let tunnel = await startSSHTunnel(user, host, localPort, remotePort);
+    let tunnel;
+    if (occupant) {
+        // Reuse the existing tunnel rather than spawning a duplicate.
+        tunnel = { pid: occupant.pid, kill: () => { try {
+                process.kill(occupant.pid);
+            }
+            catch { /* gone */ } } };
+    }
+    else {
+        tunnel = await startSSHTunnel(user, host, localPort, remotePort);
+    }
     try {
         await waitForPort(localPort, 8000);
     }
@@ -35,13 +68,28 @@ export async function connectSSH(endpoint, profile) {
     }
     const cdp = new CDPClient();
     await cdp.connect(wsUrl);
+    // Record the tunnel in the profile's runtime so a future daemon — or
+    // the orphan reaper after a crash — can find and clean it up. The
+    // `kind: 'tunnel'` flag distinguishes it from a locally-launched
+    // browser process.
+    const tunnelPid = tunnel.pid ?? 0;
+    if (tunnelPid > 0) {
+        writeProfileRuntime(profile.name, {
+            pid: 0,
+            port: localPort,
+            command: 'ssh',
+            kind: 'tunnel',
+            tunnelPid,
+        });
+    }
     return {
         cdp,
         port: localPort,
-        pid: tunnel.pid || 0,
+        pid: tunnelPid,
         cleanup: () => {
             cdp.close();
             tunnel.kill();
+            clearProfileRuntime(profile.name);
         },
     };
 }
@@ -164,3 +212,30 @@ function runSSHCommand(user, host, cmd) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Identify whether a pid listening on our target local port is an SSH
+ * tunnel WE would have spawned for `host:remotePort`. Used so that two
+ * agents-browser invocations of the same SSH profile share a tunnel
+ * rather than failing the second one with "port in use".
+ *
+ * Best-effort match against the ssh -L command line via `ps`. If we
+ * can't read the cmd or the args don't look like ours, treat as not-ours.
+ */
+function isOwnTunnel(pid, host, remotePort) {
+    try {
+        const out = execSync(`ps -p ${pid} -o command=`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).toString().trim();
+        if (!out.startsWith('ssh'))
+            return false;
+        if (!out.includes(host))
+            return false;
+        if (!out.includes(`:${remotePort}`) && !out.includes(`:127.0.0.1:${remotePort}`))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/browser/ipc.js

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { getHelpersDir } from '../state.js';
 import { startDaemon } from '../daemon.js';
+import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
 export function getSocketPath() {
     return path.join(getHelpersDir(), SOCKET_NAME);
@@ -63,6 +64,9 @@ export class BrowserIPCServer {
     }
     async handleRequest(request) {
         switch (request.action) {
+            case 'version': {
+                return { ok: true, version: getCliVersion() };
+            }
             case 'start': {
                 if (!request.profile) {
                     return { ok: false, error: 'Profile required' };
@@ -316,6 +320,21 @@ export class BrowserIPCServer {
                 const downloadPath = await this.service.waitForDownload(request.task, request.timeout);
                 return { ok: true, downloadPath };
             }
+            case 'getAppLogs': {
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
+                }
+                const appLogs = await this.service.getAppLogs(request.task, {
+                    lines: request.lines,
+                    level: request.appLevel,
+                    filter: request.filter,
+                    message: request.message,
+                    source: request.source,
+                    since: request.since,
+                    until: request.until,
+                });
+                return { ok: true, appLogs };
+            }
             case 'upload': {
                 if (!request.task || !request.files || request.files.length === 0) {
                     return { ok: false, error: 'Task and at least one file required' };
@@ -334,7 +353,43 @@ export class BrowserIPCServer {
         }
     }
 }
+let versionCheckedThisProcess = false;
+/**
+ * Check the daemon's version against ours and warn loudly when they
+ * differ. Fires at most once per CLI process — successive calls in the
+ * same `agents browser ...` invocation are cheap. The whole reason this
+ * code exists: a launchd-managed registry daemon kept serving stale code
+ * to a dev-build CLI for an entire session and nothing surfaced it.
+ */
+async function maybeWarnVersionMismatch() {
+    if (versionCheckedThisProcess)
+        return;
+    versionCheckedThisProcess = true;
+    try {
+        const resp = await sendRawIPCRequest({ action: 'version' });
+        const daemon = resp.version;
+        const client = getCliVersion();
+        if (!daemon || daemon === 'unknown' || daemon === client)
+            return;
+        process.stderr.write(`\nwarning: browser daemon is on ${daemon} but this CLI is on ${client}.\n` +
+            `         Run \`agents daemon restart\` to load the current code.\n\n`);
+    }
+    catch {
+        // daemon might be an older build that doesn't speak 'version' — that's
+        // itself a hint, but a noisy one. Stay silent on this path.
+    }
+}
 export async function sendIPCRequest(request) {
+    const result = await sendRawIPCRequest(request);
+    // Run the version check after the user's request returns — keeps the
+    // critical path zero-overhead and ensures `start` doesn't get blocked
+    // on a daemon-restart warning that the user hasn't read yet.
+    if (request.action !== 'version') {
+        maybeWarnVersionMismatch().catch(() => { });
+    }
+    return result;
+}
+async function sendRawIPCRequest(request) {
     const socketPath = getSocketPath();
     if (!fs.existsSync(socketPath)) {
         await fs.promises.mkdir(path.dirname(socketPath), { recursive: true });

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

@@ -5,8 +5,21 @@ export declare function getProfileRuntimeDir(name: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
 /**
- * Find a port in 9222–9399 that is not already claimed by another profile
- * and is not currently in use by any OS process.
+ * Compute the LOCAL port a profile will occupy at runtime:
+ *   - `cdp://127.0.0.1:N` → N (we listen on N directly)
+ *   - `ssh://host?port=N` → N (the SSH tunnel binds local N → remote N now)
+ *   - `ws[s]://`, `http[s]://` → undefined (we don't claim a local port)
+ *
+ * This is what callers should compare to detect collisions; the (host,
+ * port) tuple is no longer enough because SSH profiles do compete with
+ * cdp:// profiles for local ports under the new tunnel scheme.
+ */
+export declare function effectiveLocalPort(profile: BrowserProfile): number | undefined;
+/**
+ * Find a port in 9222–9399 that is not already claimed by ANY existing
+ * profile (cdp:// or ssh://) and is not in use by any OS process. The
+ * SSH change to bind locally on `?port=N` means we no longer get to
+ * skip remote profiles in this scan.
  */
 export declare function findFreeProfilePort(): Promise<number>;
 export declare function createProfile(profile: BrowserProfile): Promise<void>;
@@ -34,8 +47,39 @@ export declare function resolveEndpoint(profile: BrowserProfile, endpointName?:
     binary?: string;
     targetFilter?: string;
 };
+/**
+ * Extract the (host, port) pair intended by the profile's default endpoint.
+ * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Ports are scoped by host: a `cdp://127.0.0.1:9222` profile (local Chrome on
+ * this machine) and an `ssh://mac-mini:9222` profile (Comet on mac-mini)
+ * point at different physical ports — the host disambiguates them.
+ *
+ * Accepts both `scheme://host:port` and `scheme://host?port=N` shapes (the
+ * latter is the documented form in `types.ts` for `ssh://`). Without this,
+ * `ssh://mac-mini?port=18805` would silently fall back to 9222 and every
+ * `?port=`-style SSH profile would collide on creation.
+ */
+export declare function extractConfiguredEndpoint(profile: BrowserProfile): {
+    host: string;
+    port: number;
+} | undefined;
+/**
+ * Shared endpoint parser used by both the collision-detection code path and
+ * the connection drivers. Returning a single normalized `(host, port)` here
+ * keeps `extractConfiguredEndpoint` and the SSH driver from drifting on URL
+ * conventions (which is how `?port=N` ended up being silently ignored).
+ */
+export declare function parseEndpointUrl(endpoint: string): {
+    host: string;
+    port: number;
+} | undefined;
 /**
  * Extract the port intended by the profile's default endpoint.
  * Returns undefined for endpoint shapes that don't carry a port (e.g. ws:// without one).
+ *
+ * Note: this loses the host dimension — for collision detection use
+ * `extractConfiguredEndpoint` instead, which returns the (host, port) pair.
  */
 export declare function extractConfiguredPort(profile: BrowserProfile): number | undefined;
+export declare function isLocalHost(host: string): boolean;