@phnx-labs/agents-cli 1.18.6 → 1.19.1

package/dist/lib/agents.js

@@ -169,11 +169,12 @@ export const AGENTS = {
         commandsSubdir: 'prompts',
         skillsDir: path.join(HOME, '.codex', 'skills'),
         hooksDir: 'hooks',
+        pluginManifestDir: '.codex-plugin',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: false },
+        capabilities: { hooks: { since: '0.116.0' }, mcp: true, allowlist: false, skills: true, commands: { until: '0.117.0' }, plugins: { since: '0.128.0' } },
     },
     gemini: {
         id: 'gemini',
@@ -806,6 +807,12 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
     if (!agent.capabilities.mcp) {
         return { success: false, error: 'Agent does not support MCP' };
     }
+    if (transport === 'http' && agentId !== 'claude' && agentId !== 'codex' && agentId !== 'gemini') {
+        return { success: false, error: 'skipped: agent does not support HTTP MCP registration' };
+    }
+    if (transport === 'http' && options?.headers && Object.keys(options.headers).length > 0 && agentId !== 'claude') {
+        return { success: false, error: 'skipped: HTTP MCP headers are only supported for Claude registration' };
+    }
     if (!options?.binary && !(await isCliInstalled(agentId))) {
         return { success: false, error: 'CLI not installed' };
     }
@@ -813,11 +820,21 @@ export async function registerMcp(agentId, name, command, scope = 'user', transp
         // Use explicit binary path when provided (bypasses shim for version-managed agents)
         const bin = options?.binary || agent.cliCommand;
         let args;
-        const commandArgs = splitCommandLine(command);
-        if (agentId === 'claude') {
+        if (transport === 'http') {
+            if (agentId === 'codex') {
+                args = ['mcp', 'add', name, '--url', command];
+            }
+            else {
+                const headerArgs = Object.entries(options?.headers || {}).flatMap(([key, value]) => ['--header', `${key}: ${value}`]);
+                args = ['mcp', 'add', '--transport', 'http', '--scope', scope, name, command, ...headerArgs];
+            }
+        }
+        else if (agentId === 'claude') {
+            const commandArgs = splitCommandLine(command);
             args = ['mcp', 'add', '--transport', transport, '--scope', scope, name, '--', ...commandArgs];
         }
         else {
+            const commandArgs = splitCommandLine(command);
             args = ['mcp', 'add', name, '--', ...commandArgs];
         }
         // When home is specified, override HOME so MCP config writes to the version's config dir
@@ -852,15 +869,16 @@ export async function unregisterMcp(agentId, name, options) {
  * Register an MCP server across multiple agent targets, including both direct
  * (non-version-managed) agents and specific version-managed installs.
  */
-export async function registerMcpToTargets(targets, name, command, scope = 'user', transport = 'stdio') {
+export async function registerMcpToTargets(targets, name, command, scope = 'user', transport = 'stdio', options = {}) {
     const results = [];
     for (const agentId of targets.directAgents) {
-        const result = await registerMcp(agentId, name, command, scope, transport);
+        const result = await registerMcp(agentId, name, command, scope, transport, options);
         results.push({ agentId, success: result.success, error: result.error });
     }
     for (const [agentId, versions] of targets.versionSelections) {
         for (const version of versions) {
             const result = await registerMcp(agentId, name, command, scope, transport, {
+                ...options,
                 home: getVersionHomePath(agentId, version),
                 binary: getBinaryPath(agentId, version),
             });

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

@@ -1,16 +1,30 @@
+import type { Readable, Writable } from 'stream';
+export interface CDPPipeTransport {
+    read: Readable;
+    write: Writable;
+}
 type EventHandler = (params: Record<string, unknown>) => void;
+export declare function registerPipeTransport(transport: CDPPipeTransport): string;
 export declare class CDPClient {
     private ws;
+    private pipe;
+    private pipeBuffer;
+    private transport;
     private messageId;
     private pending;
     private eventHandlers;
-    connect(wsUrl: string): Promise<void>;
+    private pipeDataHandler;
+    private pipeErrorHandler;
+    private pipeCloseHandler;
+    connect(endpoint: string): Promise<void>;
+    connectPipe(transport: CDPPipeTransport): void;
     send<T = unknown>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
     on(event: string, handler: EventHandler): void;
     off(event: string, handler: EventHandler): void;
     close(): void;
     get connected(): boolean;
     get isOpen(): boolean;
+    private handlePipeData;
     private handleMessage;
     private handleClose;
 }

package/dist/lib/browser/cdp.js

@@ -1,19 +1,54 @@
+const pipeTransports = new Map();
+export function registerPipeTransport(transport) {
+    const id = `pipe://${process.pid}/${pipeTransports.size + 1}`;
+    pipeTransports.set(id, transport);
+    return id;
+}
 export class CDPClient {
     ws = null;
+    pipe = null;
+    pipeBuffer = Buffer.alloc(0);
+    transport = null;
     messageId = 0;
     pending = new Map();
     eventHandlers = new Map();
-    async connect(wsUrl) {
+    pipeDataHandler = null;
+    pipeErrorHandler = null;
+    pipeCloseHandler = null;
+    async connect(endpoint) {
+        if (endpoint.startsWith('pipe://')) {
+            const transport = pipeTransports.get(endpoint);
+            if (!transport) {
+                throw new Error('CDP pipe transport is not available in this process');
+            }
+            pipeTransports.delete(endpoint);
+            this.connectPipe(transport);
+            return;
+        }
         return new Promise((resolve, reject) => {
-            this.ws = new WebSocket(wsUrl);
+            this.ws = new WebSocket(endpoint);
+            this.transport = 'websocket';
             this.ws.onopen = () => resolve();
-            this.ws.onerror = (ev) => reject(new Error('WebSocket error'));
+            this.ws.onerror = () => reject(new Error('WebSocket error'));
             this.ws.onclose = () => this.handleClose();
             this.ws.onmessage = (ev) => this.handleMessage(String(ev.data));
         });
     }
+    connectPipe(transport) {
+        this.pipe = transport;
+        this.transport = 'pipe';
+        this.pipeBuffer = Buffer.alloc(0);
+        this.pipeDataHandler = (chunk) => this.handlePipeData(chunk);
+        this.pipeErrorHandler = (err) => this.handleClose(err);
+        this.pipeCloseHandler = () => this.handleClose();
+        transport.read.on('data', this.pipeDataHandler);
+        transport.read.on('error', this.pipeErrorHandler);
+        transport.read.on('close', this.pipeCloseHandler);
+        transport.write.on('error', this.pipeErrorHandler);
+        transport.write.on('close', this.pipeCloseHandler);
+    }
     async send(method, params, sessionId) {
-        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        if (!this.isOpen) {
             // 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
@@ -28,7 +63,12 @@ export class CDPClient {
             : JSON.stringify({ id, method, params });
         return new Promise((resolve, reject) => {
             this.pending.set(id, { resolve: resolve, reject });
-            this.ws.send(message);
+            if (this.transport === 'pipe') {
+                this.pipe.write.write(message + '\0');
+            }
+            else {
+                this.ws.send(message);
+            }
         });
     }
     on(event, handler) {
@@ -45,13 +85,40 @@ export class CDPClient {
             this.ws.close();
             this.ws = null;
         }
+        if (this.pipe) {
+            if (this.pipeDataHandler)
+                this.pipe.read.off('data', this.pipeDataHandler);
+            if (this.pipeErrorHandler) {
+                this.pipe.read.off('error', this.pipeErrorHandler);
+                this.pipe.write.off('error', this.pipeErrorHandler);
+            }
+            if (this.pipeCloseHandler) {
+                this.pipe.read.off('close', this.pipeCloseHandler);
+                this.pipe.write.off('close', this.pipeCloseHandler);
+            }
+            this.pipe.write.end();
+            this.pipe = null;
+        }
+        this.transport = null;
     }
     get connected() {
-        return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+        return ((this.ws !== null && this.ws.readyState === WebSocket.OPEN) ||
+            (this.pipe !== null && !this.pipe.write.destroyed));
     }
     get isOpen() {
         return this.connected;
     }
+    handlePipeData(chunk) {
+        this.pipeBuffer = Buffer.concat([this.pipeBuffer, chunk]);
+        let idx = this.pipeBuffer.indexOf(0);
+        while (idx !== -1) {
+            const frame = this.pipeBuffer.subarray(0, idx).toString('utf8');
+            this.pipeBuffer = this.pipeBuffer.subarray(idx + 1);
+            if (frame.length > 0)
+                this.handleMessage(frame);
+            idx = this.pipeBuffer.indexOf(0);
+        }
+    }
     handleMessage(data) {
         const msg = JSON.parse(data);
         if ('id' in msg) {
@@ -75,12 +142,14 @@ export class CDPClient {
             }
         }
     }
-    handleClose() {
+    handleClose(err) {
         for (const pending of this.pending.values()) {
-            pending.reject(new Error('CDP connection closed'));
+            pending.reject(err ?? new Error('CDP connection closed'));
         }
         this.pending.clear();
         this.ws = null;
+        this.pipe = null;
+        this.transport = null;
     }
 }
 export async function discoverBrowserWsUrl(port, host = 'localhost') {

package/dist/lib/browser/chrome.js

@@ -1,9 +1,9 @@
-import { spawn, execSync } from 'child_process';
+import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { getProfileRuntimeDir } from './profiles.js';
-import { discoverBrowserWsUrl } from './cdp.js';
+import { discoverBrowserWsUrl, registerPipeTransport } from './cdp.js';
 import { readBundle, resolveBundleEnv, bundleExists } from '../secrets/bundles.js';
 import { writeProfileRuntime, readProfileRuntime } from './runtime-state.js';
 const BROWSER_PATHS = {
@@ -88,9 +88,8 @@ isElectron = false) {
     // instance, but `ps -ww` will show both.
     const viewport = options.viewport ?? { width: 1512, height: 982 };
     const args = [
-        `--remote-debugging-port=${port}`,
+        '--remote-debugging-pipe',
         `--user-data-dir=${userDataDir}`,
-        '--remote-allow-origins=*',
         '--disable-background-timer-throttling',
         '--disable-backgrounding-occluded-windows',
         '--disable-renderer-backgrounding',
@@ -120,34 +119,26 @@ isElectron = false) {
     }
     const child = spawn(browserPath, args, {
         detached: true,
-        stdio: 'ignore',
+        stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
         env,
     });
     child.unref();
+    child.stdout?.resume();
+    child.stderr?.resume();
     const pid = child.pid;
+    const writePipe = child.stdio[3];
+    const readPipe = child.stdio[4];
+    if (!writePipe || !readPipe) {
+        throw new Error('Chrome failed to expose CDP pipe file descriptors');
+    }
+    const wsUrl = registerPipeTransport({ read: readPipe, write: writePipe });
     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);
-        try {
-            const result = await discoverBrowserWsUrl(port);
-            wsUrl = result.wsUrl;
-            break;
-        }
-        catch {
-            // Chrome still starting
-        }
-    }
-    if (!wsUrl) {
-        throw new Error('Chrome failed to start within 6 seconds');
-    }
-    return { pid, port, wsUrl };
+    return { pid, port: 0, wsUrl };
 }
 export async function attachToChrome(port) {
     const { wsUrl } = await discoverBrowserWsUrl(port);
@@ -168,6 +159,8 @@ export function getRunningChromeInfo(profileName) {
     const rt = readProfileRuntime(profileName);
     if (!rt)
         return null;
+    if (rt.port === undefined)
+        return null;
     return { pid: rt.pid, port: rt.port };
 }
 /**
@@ -196,7 +189,7 @@ export function allocatePort() {
     const max = 9300;
     for (let port = base; port < max; port++) {
         try {
-            execSync(`lsof -i :${port}`, { stdio: 'ignore' });
+            execFileSync('lsof', ['-i', `:${port}`], { stdio: 'ignore' });
         }
         catch {
             return port;
@@ -211,7 +204,7 @@ export function allocatePort() {
  */
 export function getPortOccupant(port) {
     try {
-        const out = execSync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fpcn`, {
+        const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpcn'], {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
         });

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

@@ -6,5 +6,6 @@ export interface SSHConnection {
     pid: number;
     cleanup: () => void;
 }
+export declare function shellQuote(s: string): string;
 export declare function connectSSH(endpoint: string, profile: BrowserProfile): Promise<SSHConnection>;
 export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, customBinary?: string): Promise<void>;

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

@@ -1,9 +1,14 @@
-import { spawn, execSync } from 'child_process';
+import { spawn, execFileSync } from 'child_process';
 import * as net from 'net';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
 import { getPortOccupant } from '../chrome.js';
 import { parseEndpointUrl } from '../profiles.js';
 import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
+export function shellQuote(s) {
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(s))
+        return s;
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
@@ -153,15 +158,15 @@ function tryConnect(port) {
 }
 async function ensureRemoteBrowser(user, host, browserType, port, customBinary) {
     const browserPaths = {
-        chrome: '/Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome',
+        chrome: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
         comet: '/Applications/Comet.app/Contents/MacOS/Comet',
         chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
-        brave: '/Applications/Brave\\ Browser.app/Contents/MacOS/Brave\\ Browser',
-        edge: '/Applications/Microsoft\\ Edge.app/Contents/MacOS/Microsoft\\ Edge',
+        brave: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+        edge: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
     };
     let browserPath;
     if (customBinary) {
-        browserPath = customBinary.replace(/ /g, '\\ ');
+        browserPath = customBinary;
     }
     else if (browserType === 'custom') {
         throw new Error('browser: custom requires a binary path in the profile');
@@ -172,7 +177,14 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
             throw new Error(`Unknown browser type: ${browserType}`);
         }
     }
-    const remoteCmd = `${browserPath} --remote-debugging-port=${port} '--remote-allow-origins=*' --disable-background-timer-throttling --user-data-dir=/tmp/agents-browser-${port} </dev/null >/dev/null 2>&1 &`;
+    const remoteCmd = [
+        shellQuote(browserPath),
+        `--remote-debugging-port=${port}`,
+        shellQuote('--remote-allow-origins=*'),
+        '--disable-background-timer-throttling',
+        `--user-data-dir=/tmp/agents-browser-${port}`,
+        '</dev/null >/dev/null 2>&1 &',
+    ].join(' ');
     return new Promise((resolve, reject) => {
         const child = spawn('ssh', [
             `${user}@${host}`,
@@ -190,7 +202,7 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
 }
 export async function restartRemoteBrowser(user, host, browserType, port, customBinary) {
     // Kill any process using the remote debugging port
-    const killCmd = `lsof -ti :${port} | xargs kill -9 2>/dev/null || true`;
+    const killCmd = `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
     await runSSHCommand(user, host, killCmd);
     await sleep(500);
     await ensureRemoteBrowser(user, host, browserType, port, customBinary);
@@ -223,7 +235,7 @@ function sleep(ms) {
  */
 function isOwnTunnel(pid, host, remotePort) {
     try {
-        const out = execSync(`ps -p ${pid} -o command=`, {
+        const out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
         }).toString().trim();

package/dist/lib/browser/ipc.js

@@ -6,7 +6,7 @@ import { startDaemon } from '../daemon.js';
 import { getCliVersion } from '../version.js';
 const SOCKET_NAME = 'browser.sock';
 export function getSocketPath() {
-    return path.join(getHelpersDir(), SOCKET_NAME);
+    return path.join(getHelpersDir(), 'browser', SOCKET_NAME);
 }
 export class BrowserIPCServer {
     server = null;
@@ -16,6 +16,9 @@ export class BrowserIPCServer {
     }
     async start() {
         const socketPath = getSocketPath();
+        const socketDir = path.dirname(socketPath);
+        fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+        fs.chmodSync(socketDir, 0o700);
         if (fs.existsSync(socketPath)) {
             fs.unlinkSync(socketPath);
         }
@@ -44,11 +47,32 @@ export class BrowserIPCServer {
             });
         });
         return new Promise((resolve, reject) => {
+            // Lock down the browser socket dir before opening the socket; on macOS
+            // the parent dir is the real local-user boundary for AF_UNIX sockets.
+            const prevUmask = process.umask(0o077);
+            let restored = false;
+            const restoreUmask = () => {
+                if (restored)
+                    return;
+                restored = true;
+                process.umask(prevUmask);
+            };
             this.server.listen(socketPath, () => {
-                fs.chmodSync(socketPath, 0o600);
-                resolve();
+                try {
+                    fs.chmodSync(socketPath, 0o600);
+                    resolve();
+                }
+                catch (err) {
+                    reject(err);
+                }
+                finally {
+                    restoreUmask();
+                }
+            });
+            this.server.on('error', (err) => {
+                restoreUmask();
+                reject(err);
             });
-            this.server.on('error', reject);
         });
     }
     async stop() {
@@ -63,6 +87,14 @@ export class BrowserIPCServer {
         await this.service.shutdown();
     }
     async handleRequest(request) {
+        if (request.action === 'upload-stage') {
+            const source = request.source;
+            if (!source) {
+                return { ok: false, error: 'Source required' };
+            }
+            const result = this.service.stageUpload(source);
+            return { ok: true, path: result.path };
+        }
         switch (request.action) {
             case 'version': {
                 return { ok: true, version: getCliVersion() };
@@ -392,7 +424,8 @@ export async function sendIPCRequest(request) {
 async function sendRawIPCRequest(request) {
     const socketPath = getSocketPath();
     if (!fs.existsSync(socketPath)) {
-        await fs.promises.mkdir(path.dirname(socketPath), { recursive: true });
+        await fs.promises.mkdir(path.dirname(socketPath), { recursive: true, mode: 0o700 });
+        await fs.promises.chmod(path.dirname(socketPath), 0o700);
         startDaemon();
         if (!fs.existsSync(socketPath)) {
             await new Promise((resolve, reject) => {

package/dist/lib/browser/profiles.js

@@ -1,5 +1,5 @@
 import * as path from 'path';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, writeMeta, } from '../state.js';
 import { findBrowserPath } from './chrome.js';
 export function getBrowserRuntimeDir() {
@@ -9,6 +9,7 @@ export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
 function configToProfile(name, config) {
+    validateRemoteBrowserBinaries(config);
     return {
         name,
         description: config.description,
@@ -26,6 +27,7 @@ function configToProfile(name, config) {
     };
 }
 function profileToConfig(profile) {
+    validateRemoteBrowserBinaries(profile);
     const config = {
         browser: profile.browser,
         endpoints: profile.endpoints,
@@ -112,7 +114,7 @@ export async function findFreeProfilePort() {
         if (usedByProfile.has(port))
             continue;
         try {
-            execSync(`lsof -i :${port}`, { stdio: 'ignore' });
+            execFileSync('lsof', ['-i', `:${port}`], { stdio: 'ignore' });
             // lsof succeeded → something is listening → port is in use
         }
         catch {
@@ -122,6 +124,36 @@ export async function findFreeProfilePort() {
     }
     throw new Error('No available ports in range 9222-9399');
 }
+function validateRemoteBrowserBinaries(profile) {
+    if (!hasSshEndpoint(profile.endpoints))
+        return;
+    validateRemoteBrowserBinary(profile.binary);
+    if (!Array.isArray(profile.endpoints)) {
+        for (const preset of Object.values(profile.endpoints)) {
+            validateRemoteBrowserBinary(preset.binary);
+        }
+    }
+}
+function validateRemoteBrowserBinary(binary) {
+    if (!binary)
+        return;
+    if (/[\0\r\n;&|`$<>]/.test(binary)) {
+        throw new Error(`Remote browser binary contains shell metacharacters: ${binary}`);
+    }
+}
+function hasSshEndpoint(endpoints) {
+    const targets = Array.isArray(endpoints)
+        ? endpoints
+        : Object.values(endpoints).map((preset) => preset.target);
+    return targets.some((target) => {
+        try {
+            return new URL(target).protocol === 'ssh:';
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export async function createProfile(profile) {
     const meta = readMeta();
     if (meta.browser?.[profile.name]) {

package/dist/lib/browser/runtime-state.d.ts

@@ -4,7 +4,6 @@
  *
  *  - `pid`     — child process ID we spawned (or 0 if attached to an
  *                already-running browser)
- *  - `port`    — CDP port we ended up speaking on
  *  - `command` — basename of the executable so we can defend against pid
  *                reuse (`process.kill(pid, 0)` only proves *some* process
  *                with that id exists; if the OS recycled it for an
@@ -19,7 +18,7 @@
  */
 export interface ProfileRuntime {
     pid: number;
-    port: number;
+    port?: number;
     command?: string;
     /** Full path of the user-data-dir we passed to --user-data-dir, used by the reaper to confirm. */
     userDataDir?: string;

package/dist/lib/browser/runtime-state.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { getProfileRuntimeDir, getBrowserRuntimeDir } from './profiles.js';
 const PID_FILE = 'pid';
 const PORT_FILE = 'port';
@@ -32,7 +32,15 @@ export function writeProfileRuntime(profileName, runtime) {
     const dir = getProfileRuntimeDir(profileName);
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(path.join(dir, PID_FILE), String(runtime.pid));
-    fs.writeFileSync(path.join(dir, PORT_FILE), String(runtime.port));
+    if (runtime.port !== undefined) {
+        fs.writeFileSync(path.join(dir, PORT_FILE), String(runtime.port));
+    }
+    else {
+        try {
+            fs.unlinkSync(path.join(dir, PORT_FILE));
+        }
+        catch { /* not present */ }
+    }
     if (runtime.command) {
         fs.writeFileSync(path.join(dir, COMMAND_FILE), runtime.command);
     }
@@ -241,7 +249,7 @@ export function reapOrphanedProcesses() {
 }
 function matchesCommand(pid, expectedCommand) {
     try {
-        const out = execSync(`ps -p ${pid} -o comm=`, {
+        const out = execFileSync('ps', ['-p', String(pid), '-o', 'comm='], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
         }).trim();

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

@@ -2,6 +2,7 @@ import { type TabInfo, type ProfileStatus, type HistoricalTask } from './types.j
 import { type RefOpts, type RefNode } from './refs.js';
 import type { TargetFilter } from './types.js';
 export type UploadMode = 'auto' | 'input' | 'drop' | 'chooser';
+export declare function resolveScreenshotOutputPath(outputPath: string | undefined, automaticPath: string): string;
 /**
  * Parse a `targetFilter` string into its kind + value, or return `null`
  * when the input is missing or malformed. Filter syntax:
@@ -39,6 +40,7 @@ export declare function pickWindowTarget<T extends {
  * or relative offsets like `30s`, `5m`, `2h`, `1d`.
  */
 export declare function parseSinceUntil(s: string): Date;
+export declare function readNewestMatchingRemoteFileCommand(dir: string, prefix: string, tailLines: number): string;
 export declare function readNewestMatchingFile(dir: string, prefix: string, tailLines: number): string;
 export declare class BrowserService {
     private static readonly SOURCE_PREFIX;
@@ -140,6 +142,9 @@ export declare class BrowserService {
     }): Promise<{
         mode: 'input' | 'drop' | 'chooser';
     }>;
+    stageUpload(source: string): {
+        path: string;
+    };
     status(profileName?: string): Promise<ProfileStatus[]>;
     private reconcileFromDisk;
     setViewport(taskId: string, width: number, height: number, options?: {