@claude-flow/cli 3.44.0 → 3.46.0

package/dist/src/mcp-server.d.ts

@@ -29,6 +29,7 @@ export interface MCPServerOptions {
     tools?: string[] | 'all';
     daemonize?: boolean;
     timeout?: number;
+    requestTimeoutMs?: number;
 }
 /**
  * MCP Server status
@@ -85,6 +86,21 @@ export declare class MCPServerManager extends EventEmitter {
     private startTime?;
     private healthCheckInterval?;
     private mcpServers;
+    /**
+     * This manager's own lifecycle (#3364). A stdio server keeps no PID record,
+     * so nothing on disk can answer "is this manager running?" — only the
+     * manager can. `idle` is a manager that has never started, and only there
+     * does the #2934 fallback in getStatus() ("assume a client-launched stdio
+     * server") apply; `stopped` is a handle on a server that is gone, and it
+     * says so rather than reporting whatever PID the shared file happens to hold.
+     */
+    private lifecycle;
+    /**
+     * The exact bytes this manager wrote to the PID file, while they are still
+     * there (#3364). stop() retracts the record only while it is byte for byte
+     * the one we wrote: the slot may have changed hands in between.
+     */
+    private ownedRecord;
     constructor(options?: MCPServerOptions);
     /**
      * Start the MCP server
@@ -136,15 +152,43 @@ export declare class MCPServerManager extends EventEmitter {
      */
     private startHealthMonitoring;
     /**
-     * Write PID file
+     * Write the PID record.
+     *
+     * Line 1 is the bare PID, byte for byte what this file has always held, so
+     * every existing reader keeps working: an older ruflo's
+     * `parseInt(content.trim(), 10)` stops at the newline, and
+     * `v3/scripts/start-mcp.sh` reads the first line. Line 2 is the durable
+     * identity of the instance that wrote it (#3364). Returns the bytes written,
+     * which stop() uses to retract only its own record.
      */
     private writePidFile;
     /**
-     * Read PID file
-     */
-    private readPidFile;
-    /**
-     * Remove PID file
+     * Read the PID record.
+     *
+     * A bare-integer file — an older ruflo, `start-mcp.sh --daemon`, or a
+     * hand-written one — parses to a record with no identity, which keeps
+     * exactly the old behaviour: the PID is checked for liveness and nothing
+     * more. An identity line is only believed for the PID it names.
+     */
+    private readPidRecord;
+    /**
+     * Is the recorded server still the instance the record names? (#3364)
+     *
+     * `kill -0`, and isProcessRunning()'s process-name check on top of it, only
+     * answer "something with this number is alive". Durable identity answers
+     * "it is still the one we wrote down":
+     *  - another host, OS, kernel boot or PID namespace issues its own PIDs, so
+     *    the number says nothing here. On Linux this is the ordinary stale case,
+     *    because /tmp commonly survives a reboot;
+     *  - within one boot the OS reuses a PID once the process is reaped, and the
+     *    owner's start time is what tells the two apart.
+     * Where the start time cannot be read — Windows — the answer falls back to
+     * isProcessRunning(), i.e. exactly the evidence used today.
+     */
+    private recordedServerIsLive;
+    /**
+     * Remove PID file. With `ownedRecord`, only while the file still holds
+     * exactly those bytes: the slot may have changed hands (#3364).
      */
     private removePidFile;
     /**

package/dist/src/mcp-server.js

@@ -30,6 +30,73 @@ import { isPolicyEnforcementEnabled, loadMcpPolicy, evaluateToolCall, } from './
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+/**
+ * Linux PID namespace of this process, e.g. `pid:[4026531836]`; undefined on
+ * other platforms or without /proc. A PID from another namespace (a container,
+ * a `bwrap --unshare-pid` sandbox) names a different process here.
+ */
+const PID_NAMESPACE = (() => {
+    try {
+        return fs.readlinkSync('/proc/self/ns/pid');
+    }
+    catch {
+        return undefined;
+    }
+})();
+/**
+ * Linux boot id: one uuid per kernel boot, shared by every process on that
+ * kernel and readable inside containers. `host` is only a name, and many
+ * distributions keep /tmp across a reboot — ADR-071 already names
+ * `/tmp/claude-flow-mcp.pid` as machine-wide on Linux — so without this a
+ * record written before the machine came back up looks exactly like a live one.
+ */
+const BOOT_ID = (() => {
+    try {
+        return fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+    }
+    catch {
+        return undefined;
+    }
+})();
+/**
+ * A token that changes when a PID is handed to a different process: the
+ * owner's start time.
+ *
+ * Linux reports it in /proc/<pid>/stat field 22 as clock ticks since boot,
+ * which is durable together with BOOT_ID above. Elsewhere `ps -o lstart=`
+ * reports an absolute wall-clock time, durable on its own. Returns undefined
+ * where neither exists — on Windows, so PID reuse stays unqualified there,
+ * exactly as isProcessRunning()'s process-name check already is.
+ */
+function processStartToken(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    // DA-CRIT-3: validate the PID numerically and pass it as an argv entry,
+    // never interpolated into a shell string.
+    const safePid = String(Math.floor(pid));
+    try {
+        // `pid (comm) state ppid ...` — comm is parenthesised and may itself
+        // contain spaces and parentheses, so parse after the last ')'.
+        const stat = fs.readFileSync(`/proc/${safePid}/stat`, 'utf8');
+        const afterComm = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const starttime = afterComm[19];
+        if (starttime && /^\d+$/.test(starttime))
+            return starttime;
+    }
+    catch {
+        // Not Linux, or no /proc — fall through to ps.
+    }
+    try {
+        const lstart = execFileSync('ps', ['-p', safePid, '-o', 'lstart='], {
+            encoding: 'utf8',
+            timeout: 1000,
+        }).trim();
+        return lstart || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Default configuration
  */
@@ -42,6 +109,7 @@ const DEFAULT_OPTIONS = {
     tools: 'all',
     daemonize: false,
     timeout: 30000,
+    requestTimeoutMs: 30000,
 };
 export function parseMcpToolSelection(value) {
     if (!value || value.trim().toLowerCase() === 'all')
@@ -103,6 +171,21 @@ export class MCPServerManager extends EventEmitter {
     startTime;
     healthCheckInterval;
     mcpServers = [];
+    /**
+     * This manager's own lifecycle (#3364). A stdio server keeps no PID record,
+     * so nothing on disk can answer "is this manager running?" — only the
+     * manager can. `idle` is a manager that has never started, and only there
+     * does the #2934 fallback in getStatus() ("assume a client-launched stdio
+     * server") apply; `stopped` is a handle on a server that is gone, and it
+     * says so rather than reporting whatever PID the shared file happens to hold.
+     */
+    lifecycle = 'idle';
+    /**
+     * The exact bytes this manager wrote to the PID file, while they are still
+     * there (#3364). stop() retracts the record only while it is byte for byte
+     * the one we wrote: the slot may have changed hands in between.
+     */
+    ownedRecord = null;
     constructor(options = {}) {
         super();
         // `options.tools`, populated by the `mcp start --tools` CLI flag, is
@@ -118,12 +201,35 @@ export class MCPServerManager extends EventEmitter {
      * Start the MCP server
      */
     async start() {
-        // Check if already running (skip if status reports our own PID —
-        // getStatus() returns running=true for the current process in stdio mode
-        // even before the server is actually started)
-        const status = await this.getStatus();
-        if (status.running && status.pid !== process.pid) {
-            throw new Error(`MCP Server already running (PID: ${status.pid})`);
+        // #3364: the PID file is a single slot per os.tmpdir() (per user on
+        // macOS/Windows; the machine-wide /tmp on Linux unless TMPDIR is set), and
+        // it records the port-bound (http/websocket) server, where a second
+        // instance would conflict. A stdio server is owned by the client that
+        // spawned it and any number run side by side (one per MCP client or
+        // project), so a stdio server never claims that slot, and never refuses to
+        // start over — or clears — a live server's record. ADR-071 made this
+        // singleton safe against self-detection and PID reuse; a stdio server has
+        // no business claiming it at all. What it does instead is track its own
+        // lifecycle, because for a server that leaves no record that is the only
+        // evidence there is.
+        const usesPidFile = this.options.transport !== 'stdio';
+        // Refuse to start a second port-bound server over a live one. The record
+        // is read directly rather than through getStatus(), whose #2934 fallback
+        // answers about this process, not about the recorded server — and whose
+        // own PID would otherwise have to be filtered out again here.
+        if (usesPidFile) {
+            const record = await this.readPidRecord();
+            if (record && this.recordedServerIsLive(record)) {
+                if (record.pid !== process.pid) {
+                    throw new Error(`MCP Server already running (PID: ${record.pid})`);
+                }
+            }
+            else if (record) {
+                // Stale record — a dead PID, a PID since handed to another process, or
+                // an identity from another host, kernel boot or PID namespace. Cleaned
+                // up here, as the getStatus() call this replaced used to do.
+                await this.removePidFile();
+            }
         }
         const startTime = performance.now();
         this.startTime = new Date();
@@ -137,9 +243,12 @@ export class MCPServerManager extends EventEmitter {
                 // For HTTP/WebSocket, start in-process server
                 await this.startHttpServer();
             }
+            this.lifecycle = 'running';
             const duration = performance.now() - startTime;
-            // Write PID file
-            await this.writePidFile();
+            // Write PID file, and remember the bytes so stop() retracts only ours
+            if (usesPidFile) {
+                this.ownedRecord = await this.writePidFile();
+            }
             // Start health check monitoring
             this.startHealthMonitoring();
             const finalStatus = await this.getStatus();
@@ -192,8 +301,19 @@ export class MCPServerManager extends EventEmitter {
                 this.mcpServers = [];
                 await Promise.all(servers.map((server) => server.stop()));
             }
-            // Remove PID file
-            await this.removePidFile();
+            // #3364: retract the record only if this manager wrote it, and only
+            // while it is still ours byte for byte — another server may have taken
+            // the slot. A live stdio server wrote nothing, so it has nothing to
+            // retract; a manager that never started — the one `mcp stop` builds —
+            // still clears the recorded server, exactly as before.
+            if (this.ownedRecord !== null) {
+                await this.removePidFile(this.ownedRecord);
+            }
+            else if (this.lifecycle !== 'running' || this.options.transport !== 'stdio') {
+                await this.removePidFile();
+            }
+            this.lifecycle = 'stopped';
+            this.ownedRecord = null;
             this.startTime = undefined;
             this.emit('stopped');
         }
@@ -206,9 +326,28 @@ export class MCPServerManager extends EventEmitter {
      * Get server status
      */
     async getStatus() {
+        // #3364: this manager's own lifecycle is the authority on this manager.
+        // While it is serving stdio it IS the server — it never wrote a record, so
+        // a recorded PID belongs to somebody else. Once it has stopped it is not
+        // running, whatever the record says. The marker is live lifecycle, not a
+        // one-way "has served stdio" flag that survives the server it described.
+        if (this.lifecycle === 'running' && this.options.transport === 'stdio') {
+            return {
+                running: true,
+                pid: process.pid,
+                transport: 'stdio',
+                startedAt: this.startTime?.toISOString(),
+                uptime: this.startTime
+                    ? Math.floor((Date.now() - this.startTime.getTime()) / 1000)
+                    : undefined,
+            };
+        }
+        if (this.lifecycle === 'stopped') {
+            return { running: false };
+        }
         // Check PID file
-        const pid = await this.readPidFile();
-        if (!pid) {
+        const record = await this.readPidRecord();
+        if (!record) {
             // No PID file found. Detect if we are running in stdio mode
             // (e.g., launched by Claude Code via `claude mcp add`).
             const isStdio = !process.stdin.isTTY;
@@ -226,9 +365,8 @@ export class MCPServerManager extends EventEmitter {
             }
             return { running: false };
         }
-        // Check if process is running
-        const isRunning = this.isProcessRunning(pid);
-        if (!isRunning) {
+        // Check that the recorded server is still the instance the record names
+        if (!this.recordedServerIsLive(record)) {
             // Clean up stale PID file
             await this.removePidFile();
             return { running: false };
@@ -236,7 +374,7 @@ export class MCPServerManager extends EventEmitter {
         // Build status
         const status = {
             running: true,
-            pid,
+            pid: record.pid,
             transport: this.options.transport,
             host: this.options.host,
             port: this.options.port,
@@ -256,12 +394,23 @@ export class MCPServerManager extends EventEmitter {
      */
     async checkHealth() {
         if (this.options.transport === 'stdio') {
-            // For stdio, check if process is running
-            const pid = await this.readPidFile();
-            if (pid === null) {
+            // #3364: while this manager is serving stdio it IS the server, so it is
+            // healthy by definition and must not read — or, from the 30s monitor in
+            // startHealthMonitoring(), clear — the record it deliberately never
+            // wrote. Once it has stopped it is not healthy either: it is a handle on
+            // a dead server, not a window onto whatever PID the shared file holds.
+            if (this.lifecycle === 'running') {
+                return { healthy: true };
+            }
+            if (this.lifecycle === 'stopped') {
+                return { healthy: false, error: 'Server stopped' };
+            }
+            // For stdio, check if the recorded process is running
+            const record = await this.readPidRecord();
+            if (record === null) {
                 return { healthy: false, error: 'No PID file found' };
             }
-            if (!this.isProcessRunning(pid)) {
+            if (!this.recordedServerIsLive(record)) {
                 // Clean up stale PID file
                 await this.removePidFile();
                 return { healthy: false, error: 'Process not running (cleaned up stale PID)' };
@@ -613,6 +762,7 @@ export class MCPServerManager extends EventEmitter {
             port: this.options.port,
             enableMetrics: true,
             enableCaching: true,
+            requestTimeout: this.options.requestTimeoutMs,
         }, logger);
         const registration = mcpServer.registerTools(cliTools);
         if (registration.failed.length > 0) {
@@ -674,34 +824,118 @@ export class MCPServerManager extends EventEmitter {
         this.healthCheckInterval.unref();
     }
     /**
-     * Write PID file
+     * Write the PID record.
+     *
+     * Line 1 is the bare PID, byte for byte what this file has always held, so
+     * every existing reader keeps working: an older ruflo's
+     * `parseInt(content.trim(), 10)` stops at the newline, and
+     * `v3/scripts/start-mcp.sh` reads the first line. Line 2 is the durable
+     * identity of the instance that wrote it (#3364). Returns the bytes written,
+     * which stop() uses to retract only its own record.
      */
     async writePidFile() {
         const pid = this.process?.pid || process.pid;
-        await fs.promises.writeFile(this.options.pidFile, String(pid), 'utf8');
+        const identity = {
+            v: 1,
+            pid,
+            host: os.hostname(),
+            platform: process.platform,
+            pidns: PID_NAMESPACE,
+            boot: BOOT_ID,
+            start: processStartToken(pid),
+            transport: this.options.transport,
+            port: this.options.port,
+            startedAt: (this.startTime ?? new Date()).toISOString(),
+        };
+        const record = `${pid}\n${JSON.stringify(identity)}\n`;
+        await fs.promises.writeFile(this.options.pidFile, record, 'utf8');
+        return record;
     }
     /**
-     * Read PID file
+     * Read the PID record.
+     *
+     * A bare-integer file — an older ruflo, `start-mcp.sh --daemon`, or a
+     * hand-written one — parses to a record with no identity, which keeps
+     * exactly the old behaviour: the PID is checked for liveness and nothing
+     * more. An identity line is only believed for the PID it names.
      */
-    async readPidFile() {
+    async readPidRecord() {
         try {
-            const content = await fs.promises.readFile(this.options.pidFile, 'utf8');
-            const pid = parseInt(content.trim(), 10);
-            return isNaN(pid) ? null : pid;
+            const raw = await fs.promises.readFile(this.options.pidFile, 'utf8');
+            const newline = raw.indexOf('\n');
+            const pid = parseInt((newline === -1 ? raw : raw.slice(0, newline)).trim(), 10);
+            if (!Number.isInteger(pid) || pid <= 0)
+                return null;
+            let identity;
+            const rest = newline === -1 ? '' : raw.slice(newline + 1).trim();
+            if (rest) {
+                try {
+                    const parsed = JSON.parse(rest);
+                    if (parsed && parsed.v === 1 && parsed.pid === pid)
+                        identity = parsed;
+                }
+                catch {
+                    // Truncated, or a second line we don't recognise — PID only.
+                }
+            }
+            return { pid, raw, identity };
         }
         catch {
             return null;
         }
     }
     /**
-     * Remove PID file
+     * Is the recorded server still the instance the record names? (#3364)
+     *
+     * `kill -0`, and isProcessRunning()'s process-name check on top of it, only
+     * answer "something with this number is alive". Durable identity answers
+     * "it is still the one we wrote down":
+     *  - another host, OS, kernel boot or PID namespace issues its own PIDs, so
+     *    the number says nothing here. On Linux this is the ordinary stale case,
+     *    because /tmp commonly survives a reboot;
+     *  - within one boot the OS reuses a PID once the process is reaped, and the
+     *    owner's start time is what tells the two apart.
+     * Where the start time cannot be read — Windows — the answer falls back to
+     * isProcessRunning(), i.e. exactly the evidence used today.
      */
-    async removePidFile() {
-        try {
-            await fs.promises.unlink(this.options.pidFile);
+    recordedServerIsLive(record) {
+        const { pid, identity } = record;
+        if (identity) {
+            if (identity.host !== os.hostname() ||
+                identity.platform !== process.platform ||
+                identity.pidns !== PID_NAMESPACE ||
+                identity.boot !== BOOT_ID) {
+                return false;
+            }
+            if (identity.start !== undefined) {
+                const start = processStartToken(pid);
+                if (start !== undefined && start !== identity.start)
+                    return false;
+            }
         }
-        catch {
-            // Ignore errors
+        return this.isProcessRunning(pid);
+    }
+    /**
+     * Remove PID file. With `ownedRecord`, only while the file still holds
+     * exactly those bytes: the slot may have changed hands (#3364).
+     */
+    async removePidFile(ownedRecord) {
+        let ours = true;
+        if (ownedRecord !== undefined) {
+            try {
+                ours = (await fs.promises.readFile(this.options.pidFile, 'utf8')) === ownedRecord;
+            }
+            catch {
+                ours = false; // Already gone
+            }
+        }
+        if (ours) {
+            try {
+                await fs.promises.unlink(this.options.pidFile);
+            }
+            catch {
+                // Ignore errors
+            }
         }
         // Also clean up legacy PID file location from older versions
         try {

package/dist/src/mcp-tools/agent-execute-core.js

@@ -454,7 +454,14 @@ export async function executeAgentTask(input) {
     // Kept for legacy error-path remediation message + final-result `model` field
     // (returned when the request fully fails with no successful retry).
     const anthropicModel = firstCallModel;
+    // The agent registry persists per-agent instructions, including those set
+    // through agent_update. Workflow steps do not supply a systemPrompt, so
+    // omitting this fallback silently discards the configured agent context.
+    const configuredInstructions = typeof agent.config?.instructions === 'string' && agent.config.instructions.trim()
+        ? agent.config.instructions
+        : undefined;
     const systemPrompt = input.systemPrompt ||
+        configuredInstructions ||
         `You are a ${agent.agentType} agent operating as part of a Ruflo swarm. ` +
             `Agent ID: ${input.agentId}. Domain: ${agent.domain ?? 'general'}. ` +
             `Respond directly and stay focused on the task. If you need information you don't have, state that explicitly.`;

package/dist/src/mcp-tools/agentdb-tools.js

@@ -1060,7 +1060,7 @@ export const agentdbCausalNodeDelete = {
 };
 export const agentdbGraphQuery = {
     name: 'agentdb_graph-query',
-    description: 'Unified graph traversal across the knowledge graph (ADR-130). Dispatches to the most capable backend: graph-node native for k-hop, sql.js CTE for fallback, HNSW cosine for semantic, ruflo-graph-intelligence PageRank for pagerank mode. Use when you need structured graph traversal beyond flat memory search.',
+    description: 'Unified graph traversal across the knowledge graph (ADR-130). Native graph-node k-hop cannot filter by relation and returns an explicit unsupported error for that request; the SQL fallback can filter by relation. Inspect appliedDepth/truncated because SQL is bounded at 3 hops. Semantic and PageRank modes use their own backends. Use when you need structured graph traversal beyond flat memory search.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -1070,7 +1070,7 @@ export const agentdbGraphQuery = {
                 enum: ['k-hop', 'semantic', 'pagerank'],
                 description: 'Query mode: k-hop neighbor expansion, semantic cosine search, or PageRank scoring',
             },
-            depth: { type: 'number', description: 'Hop depth for k-hop mode (default 2, max 5)' },
+            depth: { type: 'number', description: 'Requested k-hop depth (default 2, max 5); SQL responses report appliedDepth and truncated when limited to 3' },
             topK: { type: 'number', description: 'Max results for semantic and pagerank modes (default 10)' },
             relation: { type: 'string', description: 'Optional edge relation filter' },
             complexityBudget: {
@@ -1111,13 +1111,19 @@ export const agentdbGraphQuery = {
             const relation = validateString(params.relation, 'relation', 200) ?? undefined;
             // ── k-hop mode ──────────────────────────────────────────────────────────
             if (mode === 'k-hop') {
-                // Try graph-node native first
+                // graph-node's kHopNeighbors API has no relation parameter. Its graph
+                // and the SQL graph are separate stores, and SQL writes can be async;
+                // switching stores here could report a false negative. Refuse the
+                // unsupported native query instead of silently widening it.
                 try {
                     const graphBackend = await getGraphBackend();
                     if (await graphBackend.isGraphBackendAvailable()) {
+                        if (relation) {
+                            return { success: false, error: 'Native graph-node k-hop does not support relation filtering', unsupported: 'relation', mode, nodeId, relation, backend: 'graph-node' };
+                        }
                         const neighbors = await graphBackend.getNeighbors(nodeId, depth);
                         return {
-                            success: true, mode, nodeId, depth,
+                            success: true, mode, nodeId, depth, appliedDepth: depth,
                             results: neighbors.map(id => ({ nodeId: id })),
                             count: neighbors.length,
                             backend: 'graph-node',
@@ -1125,20 +1131,23 @@ export const agentdbGraphQuery = {
                         };
                     }
                 }
-                catch { /* fall through to sql.js */ }
-                // SQL CTE fallback for k-hop up to depth 3
+                catch { /* fall through to SQL */ }
+                // SQL CTE fallback is bounded at depth 3. Report that bound so callers
+                // cannot mistake an incomplete depth-5 cycle check for a complete one.
                 try {
                     const { getBridgeDb } = await getGraphEdgeWriter();
                     const db = await getBridgeDb();
                     if (db) {
-                        const cteSql = buildKHopCTE(nodeId, Math.min(depth, 3), relation, budget.maxNodesVisited);
+                        const appliedDepth = Math.min(depth, 3);
+                        const cteSql = buildKHopCTE(nodeId, appliedDepth, relation, budget.maxNodesVisited);
                         // graph-edge-writer returns a better-sqlite3 Database after #2431.
                         // `db.exec(sql, params)` (sql.js style) is a runner with no result
                         // on better-sqlite3 — use `prepare(sql).raw().all(...)` to get the
                         // same array-of-arrays shape the downstream code expects.
                         const rows = db.prepare(cteSql).raw().all();
                         return {
-                            success: true, mode, nodeId, depth,
+                            success: true, mode, nodeId, depth, appliedDepth,
+                            ...(appliedDepth < depth ? { truncated: true } : {}),
                             results: rows.map((r) => ({ nodeId: r[0], depth: r[1] })),
                             count: rows.length,
                             backend: 'sql-cte',
@@ -1147,6 +1156,9 @@ export const agentdbGraphQuery = {
                     }
                 }
                 catch { /* db unavailable */ }
+                if (relation) {
+                    return { success: false, error: 'Relation-filtered k-hop query requires the SQL graph_edges backend', mode, nodeId, relation };
+                }
                 return { success: false, error: 'No graph backend available for k-hop query', mode, nodeId };
             }
             // ── semantic mode ────────────────────────────────────────────────────────

package/dist/src/mcp-tools/browser-tools.js

@@ -8,6 +8,34 @@ import { readFileSync, existsSync } from 'node:fs';
 import { validateIdentifier, validateText } from './validate-input.js';
 // Session registry for multi-session support
 const browserSessions = new Map();
+/** Preserve agent-browser's JSON error on non-zero exit without echoing other process output. */
+function browserCommandFailure(error, missingExecutable) {
+    const err = error;
+    const stdout = typeof err?.stdout === 'string'
+        ? err.stdout
+        : Buffer.isBuffer(err?.stdout) ? err.stdout.toString('utf8') : '';
+    let reason;
+    if (stdout.trim()) {
+        try {
+            const parsed = JSON.parse(stdout);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const failure = parsed;
+                if (failure.success === false && typeof failure.error === 'string' && failure.error.trim()) {
+                    reason = failure.error.slice(0, 2000);
+                }
+            }
+        }
+        catch { /* non-JSON stdout is not an error message */ }
+    }
+    reason ??= err?.code === 'ENOENT' && missingExecutable
+        ? missingExecutable
+        : err?.code === 'ETIMEDOUT'
+            ? 'agent-browser command timed out'
+            : typeof err?.status === 'number'
+                ? `agent-browser exited with status ${err.status} without a JSON error`
+                : `agent-browser failed${err?.code ? ` (${err.code})` : ''} without a JSON error`;
+    return { content: [{ type: 'text', text: JSON.stringify({ success: false, error: reason }) }], isError: true };
+}
 /**
  * Execute agent-browser CLI command.
  * Tries global agent-browser first, falls back to npx if ENOENT.
@@ -43,32 +71,11 @@ export async function execBrowserCommand(args, session = 'default') {
                 });
             }
             catch (npxError) {
-                const npxErr = npxError;
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                success: false,
-                                error: npxErr.code === 'ENOENT'
-                                    ? 'Neither agent-browser nor npx found. Install with: npm i -g agent-browser'
-                                    : npxErr instanceof Error ? npxErr.message : String(npxError),
-                            }),
-                        }],
-                    isError: true,
-                };
+                return browserCommandFailure(npxError, 'Neither agent-browser nor npx found. Install with: npm i -g agent-browser');
             }
         }
         else {
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            success: false,
-                            error: err instanceof Error ? err.message : String(error),
-                        }),
-                    }],
-                isError: true,
-            };
+            return browserCommandFailure(error);
         }
     }
     let data;