@vscode/component-explorer-cli 0.1.1-8 → 0.2.0

package/dist/mcp/McpServer.js

@@ -9,6 +9,7 @@ import '../external/vscode-observables/observables/dist/observableInternal/obser
 import '../external/vscode-observables/observables/dist/observableInternal/utils/utils.js';
 import '../external/vscode-observables/observables/dist/observableInternal/observables/observableFromEvent.js';
 import { buildExplorerUrl } from '../utils.js';
+import { TaskManager } from './TaskManager.js';
 
 // ---------------------------------------------------------------------------
 // Client-local state
@@ -70,9 +71,22 @@ function noDaemonError(hint) {
 // ---------------------------------------------------------------------------
 class DaemonConnection {
     client;
+    _stale = false;
     constructor(client) {
         this.client = client;
     }
+    get isStale() { return this._stale; }
+    markStale() { this._stale = true; }
+}
+function isPipeConnectionError(e) {
+    if (!(e instanceof Error)) {
+        return false;
+    }
+    const code = e.code;
+    if (code === 'ENOENT' || code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'EPIPE') {
+        return true;
+    }
+    return /connect ENOENT|ECONNREFUSED|ECONNRESET|EPIPE/.test(e.message);
 }
 // ---------------------------------------------------------------------------
 // ComponentExplorerMcpServer
@@ -87,6 +101,8 @@ class ComponentExplorerMcpServer extends Disposable {
     }
     _mcp;
     _watchList = new WatchList();
+    _taskManager = new TaskManager();
+    _taskLastReportedIndex = new Map();
     _pollFn;
     _noAutostartHint;
     _multiSessionTools = [];
@@ -97,6 +113,7 @@ class ComponentExplorerMcpServer extends Disposable {
         this._daemonConnection = _daemonConnection;
         this._pollFn = options.pollFn;
         this._noAutostartHint = options.noAutostartHint;
+        this._callTimeoutMs = options.callTimeoutMs ?? ComponentExplorerMcpServer._DEFAULT_CALL_TIMEOUT_MS;
         this._mcp = new McpServer({
             name: 'component-explorer',
             version: '0.1.0',
@@ -108,7 +125,6 @@ class ComponentExplorerMcpServer extends Disposable {
         }));
     }
     async _onDaemonChanged(daemon) {
-        // Cancel any existing event stream
         this._eventStreamAbortController?.abort();
         this._eventStreamAbortController = undefined;
         if (!daemon) {
@@ -116,10 +132,9 @@ class ComponentExplorerMcpServer extends Disposable {
             this._log('info', { type: 'daemon-disconnected' });
             return;
         }
-        // Fetch sessions and start event listener
         try {
             this._sessions = await daemon.methods.sessions();
-            this._log('info', { type: 'daemon-connected', sessions: this._sessions.length });
+            this._log('debug', { type: 'daemon-connected', sessions: this._sessions.length });
             this._updateMultiSessionToolVisibility();
             this._startEventListener(daemon);
         }
@@ -128,37 +143,77 @@ class ComponentExplorerMcpServer extends Disposable {
             this._sessions = [];
         }
     }
-    _getDaemon() {
-        return this._daemonConnection.get()?.client;
+    _getConnection() {
+        const conn = this._daemonConnection.get();
+        if (conn?.isStale) {
+            return undefined;
+        }
+        return conn;
     }
-    /**
-     * If no daemon is connected and we have a pollFn, poll immediately and wait
-     * up to 3 seconds for the daemon to become available.
-     */
     async _waitForDaemon() {
-        let daemon = this._getDaemon();
-        if (daemon || !this._pollFn) {
-            return daemon;
+        let conn = this._getConnection();
+        if (conn) {
+            return conn.client;
         }
-        // Poll immediately and wait up to 3 seconds
+        if (!this._pollFn) {
+            return undefined;
+        }
+        this._log('debug', { type: 'waiting-for-daemon' });
         const startTime = Date.now();
         const timeout = 3000;
         while (Date.now() - startTime < timeout) {
             await this._pollFn();
-            daemon = this._getDaemon();
-            if (daemon) {
-                return daemon;
+            conn = this._getConnection();
+            if (conn) {
+                return conn.client;
             }
-            // Wait 200ms before next poll
             await new Promise(resolve => setTimeout(resolve, 200));
         }
         return undefined;
     }
+    _handleDisconnect() {
+        const conn = this._daemonConnection.get();
+        if (conn && !conn.isStale) {
+            conn.markStale();
+            this._sessions = [];
+            this._log('debug', { type: 'daemon-connection-lost' });
+        }
+    }
     _noDaemonError() {
         return noDaemonError(this._noAutostartHint);
     }
+    static _DEFAULT_CALL_TIMEOUT_MS = 15_000;
+    _callTimeoutMs;
+    async _withDaemon(fn, options) {
+        const daemon = await this._waitForDaemon();
+        if (!daemon) {
+            return this._noDaemonError();
+        }
+        try {
+            if (options?.noTimeout) {
+                return await fn(daemon);
+            }
+            const timeout = new Promise((_, reject) => setTimeout(() => reject(new Error('__mcp_timeout__')), this._callTimeoutMs));
+            return await Promise.race([fn(daemon), timeout]);
+        }
+        catch (e) {
+            if (e instanceof Error && e.message === '__mcp_timeout__') {
+                return {
+                    content: [{ type: 'text', text: `Error: Operation timed out after ${this._callTimeoutMs / 1000}s. Retry, if the error persists, restart the involved session using the restart_session tool and retry.` }],
+                    isError: true,
+                };
+            }
+            if (isPipeConnectionError(e)) {
+                this._log('debug', { type: 'daemon-call-failed', error: String(e) });
+                this._handleDisconnect();
+                return this._noDaemonError();
+            }
+            throw e;
+        }
+    }
     _log(level, data) {
-        this._mcp.sendLoggingMessage({ level, logger: 'daemon', data }).catch(() => { });
+        const mcpLevel = level === 'trace' ? 'debug' : level;
+        this._mcp.sendLoggingMessage({ level: mcpLevel, logger: 'daemon', data }).catch(() => { });
     }
     _startEventListener(daemon) {
         const controller = new AbortController();
@@ -173,7 +228,7 @@ class ComponentExplorerMcpServer extends Disposable {
                     if (event.type === 'source-change' && event.sessionName && event.sourceTreeId) {
                         this._updateSessionSourceTreeId(event.sessionName, event.sourceTreeId);
                     }
-                    if (event.type === 'ref-change') {
+                    if (event.type === 'ref-change' || event.type === 'session-change') {
                         await this._refreshSessions();
                     }
                     this._log(event.type === 'log' && event.level === 'debug' ? 'debug' : 'info', event);
@@ -209,12 +264,22 @@ class ComponentExplorerMcpServer extends Disposable {
         }
     }
     async _refreshSessions() {
-        const daemon = this._getDaemon();
-        if (daemon) {
-            const prevCount = this._sessions.length;
-            this._sessions = await daemon.methods.sessions();
-            if (this._sessions.length !== prevCount) {
-                this._updateMultiSessionToolVisibility();
+        const conn = this._getConnection();
+        if (conn) {
+            try {
+                const prevCount = this._sessions.length;
+                this._sessions = await conn.client.methods.sessions();
+                if (this._sessions.length !== prevCount) {
+                    this._updateMultiSessionToolVisibility();
+                }
+            }
+            catch (e) {
+                if (isPipeConnectionError(e)) {
+                    this._handleDisconnect();
+                }
+                else {
+                    throw e;
+                }
             }
         }
     }
@@ -243,6 +308,30 @@ class ComponentExplorerMcpServer extends Disposable {
         }
     }
     // -- Tool registration ---------------------------------------------------
+    _filterFixtures(allFixtures, fixtureIdPattern, labelPattern) {
+        let fixtureIdRegex;
+        if (fixtureIdPattern) {
+            try {
+                fixtureIdRegex = new RegExp(fixtureIdPattern);
+            }
+            catch {
+                return { error: `Error: Invalid fixtureIdPattern: ${fixtureIdPattern}` };
+            }
+        }
+        let labelRegex;
+        if (labelPattern) {
+            try {
+                labelRegex = new RegExp(labelPattern);
+            }
+            catch {
+                return { error: `Error: Invalid labelPattern: ${labelPattern}` };
+            }
+        }
+        return {
+            fixtures: allFixtures.filter(f => (!fixtureIdRegex || fixtureIdRegex.test(f.fixtureId)) &&
+                (!labelRegex || f.labels.some(l => labelRegex.test(l)))),
+        };
+    }
     _registerTools() {
         this._registerListFixtures();
         this._registerScreenshot();
@@ -256,30 +345,40 @@ class ComponentExplorerMcpServer extends Disposable {
         this._registerWatchCompare();
         this._registerWaitForUpdate();
         this._registerSessions();
+        this._registerRestartSession();
+        this._registerOpenSession();
+        this._registerCloseSession();
+        this._registerUpdateSessionRef();
         this._registerGetUrl();
+        this._registerCheckStability();
+        this._registerCheckTask();
+        this._registerCancelTask();
     }
     _registerListFixtures() {
         this._mcp.registerTool('list_fixtures', {
             description: 'List all fixtures from a session',
             inputSchema: {
+                fixtureIdPattern: z.string().optional().describe('RegExp to filter fixtures by fixture ID'),
+                labelPattern: z.string().optional().describe('RegExp to filter fixtures by label (matched against inherited labels)'),
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
                 sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
             },
             annotations: { readOnlyHint: true },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'list_fixtures', sessionName });
             return this._withSourceTreeRetry(async () => {
                 const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
-                const fixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const filtered = this._filterFixtures(allFixtures, args.fixtureIdPattern, args.labelPattern);
+                if ('error' in filtered) {
+                    return { content: [{ type: 'text', text: filtered.error }], isError: true };
+                }
                 return {
-                    content: [{ type: 'text', text: JSON.stringify(fixtures, null, 2) }],
+                    content: [{ type: 'text', text: JSON.stringify(filtered.fixtures, null, 2) }],
                 };
             });
-        });
+        }));
     }
     _registerScreenshot() {
         this._mcp.registerTool('screenshot', {
@@ -292,12 +391,10 @@ class ComponentExplorerMcpServer extends Disposable {
                 stabilityCheck: z.boolean().optional().describe('If true, takes three screenshots (at render time, ~500ms, ~3000ms) to check visual stability. Expensive (~3s extra) — only use it when you need to verify rendering stability..'),
             },
             annotations: { readOnlyHint: true },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'screenshot', fixtureId: args.fixtureId, sessionName });
+            this._log('trace', { type: 'tool-args', tool: 'screenshot', args });
             return this._withSourceTreeRetry(async () => {
                 const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
                 const result = await daemon.methods.screenshots.take({
@@ -313,8 +410,17 @@ class ComponentExplorerMcpServer extends Disposable {
                     hash: r.hash,
                     sourceTreeId: r.sourceTreeId,
                 };
-                if (r.errors && r.errors.length > 0) {
-                    info.errors = r.errors;
+                if (r.hasError) {
+                    info.hasError = true;
+                }
+                if (r.error) {
+                    info.error = r.error;
+                }
+                if (r.events && r.events.length > 0) {
+                    info.events = r.events;
+                }
+                if (r.resultData !== undefined) {
+                    info.resultData = r.resultData;
                 }
                 if (r.isStable !== undefined) {
                     info.isStable = r.isStable;
@@ -340,7 +446,7 @@ class ComponentExplorerMcpServer extends Disposable {
                 content.unshift({ type: 'text', text: JSON.stringify(info, null, 2) });
                 return { content };
             });
-        });
+        }));
     }
     _registerCompareScreenshot() {
         const tool = this._mcp.registerTool('compare_screenshot', {
@@ -353,13 +459,10 @@ class ComponentExplorerMcpServer extends Disposable {
                 currentSourceTreeId: z.string().optional().describe('Current source tree ID (defaults to latest known)'),
             },
             annotations: { readOnlyHint: true },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const baselineSessionName = args.baselineSessionName ?? this._defaultBaselineSessionName();
             const currentSessionName = args.currentSessionName ?? this._defaultCurrentSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'compare_screenshot', fixtureId: args.fixtureId, baselineSessionName, currentSessionName });
             return this._withSourceTreeRetry(async () => {
                 const baselineSourceTreeId = args.baselineSourceTreeId ?? this._sourceTreeId(baselineSessionName);
                 const currentSourceTreeId = args.currentSourceTreeId ?? this._sourceTreeId(currentSessionName);
@@ -376,12 +479,32 @@ class ComponentExplorerMcpServer extends Disposable {
                     match: r.match,
                     baselineHash: r.baselineHash,
                     currentHash: r.currentHash,
+                    baselineSourceTreeId,
+                    currentSourceTreeId,
                 };
-                if (r.baselineErrors && r.baselineErrors.length > 0) {
-                    info.baselineErrors = r.baselineErrors;
+                if (r.baselineHasError) {
+                    info.baselineHasError = true;
+                }
+                if (r.baselineError) {
+                    info.baselineError = r.baselineError;
+                }
+                if (r.baselineEvents && r.baselineEvents.length > 0) {
+                    info.baselineEvents = r.baselineEvents;
+                }
+                if (r.baselineResultData !== undefined) {
+                    info.baselineResultData = r.baselineResultData;
                 }
-                if (r.currentErrors && r.currentErrors.length > 0) {
-                    info.currentErrors = r.currentErrors;
+                if (r.currentHasError) {
+                    info.currentHasError = true;
+                }
+                if (r.currentError) {
+                    info.currentError = r.currentError;
+                }
+                if (r.currentEvents && r.currentEvents.length > 0) {
+                    info.currentEvents = r.currentEvents;
+                }
+                if (r.currentResultData !== undefined) {
+                    info.currentResultData = r.currentResultData;
                 }
                 if (r.approval) {
                     info.approval = r.approval;
@@ -397,7 +520,7 @@ class ComponentExplorerMcpServer extends Disposable {
                 }
                 return { content };
             });
-        });
+        }));
         tool.disable();
         this._multiSessionTools.push(tool);
     }
@@ -410,11 +533,7 @@ class ComponentExplorerMcpServer extends Disposable {
                 modifiedHash: z.string(),
                 comment: z.string().describe('Reason for approving this diff'),
             },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             await daemon.methods.approvals.approve(args);
             return {
                 content: [{
@@ -422,7 +541,7 @@ class ComponentExplorerMcpServer extends Disposable {
                         text: `Approved diff for ${args.fixtureId}: ${args.originalHash} → ${args.modifiedHash}`,
                     }],
             };
-        });
+        }));
         tool.disable();
         this._multiSessionTools.push(tool);
     }
@@ -438,12 +557,10 @@ class ComponentExplorerMcpServer extends Disposable {
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
                 sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
             },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'evaluate_js', sessionName, hasFixtureId: !!args.fixtureId });
+            this._log('trace', { type: 'tool-args', tool: 'evaluate_js', expressionLength: args.expression.length, fixtureId: args.fixtureId });
             return this._withSourceTreeRetry(async () => {
                 const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
                 const result = await daemon.methods.evaluate({
@@ -464,7 +581,7 @@ class ComponentExplorerMcpServer extends Disposable {
                     content: [{ type: 'text', text }],
                 };
             });
-        });
+        }));
     }
     _registerDebugReloadPage() {
         this._mcp.registerTool('debug_reload_page', {
@@ -475,11 +592,7 @@ class ComponentExplorerMcpServer extends Disposable {
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
             },
             annotations: { destructiveHint: true },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const sessionName = args.sessionName ?? this._defaultSessionName();
             const sourceTreeId = this._sourceTreeId(sessionName);
             await daemon.methods.evaluate({
@@ -490,7 +603,7 @@ class ComponentExplorerMcpServer extends Disposable {
             return {
                 content: [{ type: 'text', text: `Reloaded page for session '${sessionName}'.` }],
             };
-        });
+        }));
     }
     _registerWatchAdd() {
         this._mcp.registerTool('watch_add', {
@@ -550,11 +663,7 @@ class ComponentExplorerMcpServer extends Disposable {
                 currentSourceTreeId: z.string().optional().describe('Current source tree ID (defaults to latest known)'),
             },
             annotations: { readOnlyHint: true },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const ids = [...this._watchList.fixtureIds];
             if (ids.length === 0) {
                 return { content: [{ type: 'text', text: 'Watch list is empty. Use watch_add or watch_set first.' }] };
@@ -607,7 +716,7 @@ class ComponentExplorerMcpServer extends Disposable {
                     content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
                 };
             });
-        });
+        }));
         tool.disable();
         this._multiSessionTools.push(tool);
     }
@@ -622,14 +731,9 @@ class ComponentExplorerMcpServer extends Disposable {
                 sessionName: z.string().optional().describe('Session name (defaults to first session)'),
             },
             annotations: { readOnlyHint: true },
-        }, async (args) => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async (args) => this._withDaemon(async (daemon) => {
             const sessionName = args.sessionName ?? this._defaultSessionName();
             const knownSourceTreeId = args.sourceTreeId;
-            // Check if already changed
             const currentSourceTreeId = this._sourceTreeId(sessionName);
             if (currentSourceTreeId && currentSourceTreeId !== knownSourceTreeId) {
                 return this._waitForUpdateResult(daemon, sessionName, currentSourceTreeId);
@@ -638,8 +742,13 @@ class ComponentExplorerMcpServer extends Disposable {
             const events = await daemon.methods.events();
             const iterator = events[Symbol.asyncIterator]();
             try {
-                const timeout = new Promise(resolve => setTimeout(() => resolve('timeout'), 5000));
+                const deadline = Date.now() + 5000;
                 while (true) {
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0) {
+                        return { content: [{ type: 'text', text: JSON.stringify({ timeout: true, sessionName, sourceTreeId: knownSourceTreeId }, null, 2) }] };
+                    }
+                    const timeout = new Promise(resolve => setTimeout(() => resolve('timeout'), remaining));
                     const next = iterator.next();
                     const result = await Promise.race([next, timeout]);
                     if (result === 'timeout') {
@@ -654,7 +763,10 @@ class ComponentExplorerMcpServer extends Disposable {
                         this._updateSessionSourceTreeId(ev.sessionName, ev.sourceTreeId);
                     }
                     if (ev.type === 'ref-change') {
-                        await this._refreshSessions();
+                        const refreshResult = await Promise.race([this._refreshSessions(), timeout]);
+                        if (refreshResult === 'timeout') {
+                            return { content: [{ type: 'text', text: JSON.stringify({ timeout: true, sessionName, sourceTreeId: knownSourceTreeId }, null, 2) }] };
+                        }
                     }
                     const newSourceTreeId = this._sourceTreeId(sessionName);
                     if (newSourceTreeId && newSourceTreeId !== knownSourceTreeId) {
@@ -665,7 +777,7 @@ class ComponentExplorerMcpServer extends Disposable {
             finally {
                 await iterator.return?.();
             }
-        });
+        }));
     }
     async _waitForUpdateResult(daemon, sessionName, sourceTreeId) {
         const watchedIds = [...this._watchList.fixtureIds];
@@ -708,16 +820,96 @@ class ComponentExplorerMcpServer extends Disposable {
         this._mcp.registerTool('sessions', {
             description: 'List active sessions with their names, URLs, and current sourceTreeIds',
             annotations: { readOnlyHint: true },
-        }, async () => {
-            const daemon = await this._waitForDaemon();
-            if (!daemon) {
-                return this._noDaemonError();
-            }
+        }, async () => this._withDaemon(async (_daemon) => {
             await this._refreshSessions();
             return {
                 content: [{ type: 'text', text: JSON.stringify(this._sessions, null, 2) }],
             };
-        });
+        }));
+    }
+    _registerRestartSession() {
+        this._mcp.registerTool('restart_session', {
+            description: 'Restart a session by disposing its browser page and dev server, then recreating them. ' +
+                'Use this when a session appears stuck (e.g. after a timeout).',
+            inputSchema: {
+                sessionName: z.string().optional().describe('Session name to restart (defaults to first session)'),
+            },
+            annotations: { destructiveHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('info', { type: 'tool-call', tool: 'restart_session', sessionName });
+            const sessions = await daemon.methods.restartSession({ sessionName });
+            this._sessions = sessions;
+            return {
+                content: [{ type: 'text', text: `Session '${sessionName}' restarted.\n` + JSON.stringify(sessions, null, 2) }],
+            };
+        }));
+    }
+    _registerOpenSession() {
+        this._mcp.registerTool('open_session', {
+            description: 'Open a new worktree-backed session at a given git ref. ' +
+                'The ref can be a branch name, tag, commit SHA, or the special value "INDEX" to snapshot staged changes. ' +
+                'The daemon allocates a reusable worktree slot from a fixed pool (max configured in component-explorer.json). ' +
+                'Returns the updated session list on success.',
+            inputSchema: {
+                name: z.string().describe('Unique session name (e.g. "baseline", "bisect")'),
+                ref: z.string().describe('Git ref: branch, tag, commit SHA, or "INDEX" for staged changes'),
+            },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            this._log('info', { type: 'tool-call', tool: 'open_session', name: args.name, ref: args.ref });
+            const result = await daemon.methods.openSession({ name: args.name, ref: args.ref });
+            if ('error' in result) {
+                return { content: [{ type: 'text', text: result.error }], isError: true };
+            }
+            this._sessions = result.sessions;
+            this._updateMultiSessionToolVisibility();
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.sessions, null, 2) }],
+            };
+        }, { noTimeout: true }));
+    }
+    _registerCloseSession() {
+        this._mcp.registerTool('close_session', {
+            description: 'Close a dynamic worktree session and release its worktree slot back to the pool. ' +
+                'Cannot close static sessions configured in component-explorer.json.',
+            inputSchema: {
+                name: z.string().describe('Session name to close'),
+            },
+            annotations: { destructiveHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            this._log('info', { type: 'tool-call', tool: 'close_session', name: args.name });
+            const result = await daemon.methods.closeSession({ name: args.name });
+            if ('error' in result) {
+                return { content: [{ type: 'text', text: result.error }], isError: true };
+            }
+            this._sessions = result.sessions;
+            this._updateMultiSessionToolVisibility();
+            return {
+                content: [{ type: 'text', text: `Session '${args.name}' closed.\n` + JSON.stringify(result.sessions, null, 2) }],
+            };
+        }));
+    }
+    _registerUpdateSessionRef() {
+        this._mcp.registerTool('update_session_ref', {
+            description: 'Change the git ref of an existing dynamic session. ' +
+                'The worktree is checked out to the new ref and Vite\'s HMR handles the incremental update (no server restart). ' +
+                'Fails if the worktree has uncommitted changes — the error will list the dirty files. ' +
+                'The ref can be a branch, tag, commit SHA, or "INDEX" for staged changes.',
+            inputSchema: {
+                name: z.string().describe('Session name to update'),
+                ref: z.string().describe('New git ref: branch, tag, commit SHA, or "INDEX"'),
+            },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            this._log('info', { type: 'tool-call', tool: 'update_session_ref', name: args.name, ref: args.ref });
+            const result = await daemon.methods.updateSessionRef({ name: args.name, ref: args.ref });
+            if ('error' in result) {
+                return { content: [{ type: 'text', text: result.error }], isError: true };
+            }
+            this._sessions = result.sessions;
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result.sessions, null, 2) }],
+            };
+        }, { noTimeout: true }));
     }
     _registerGetUrl() {
         this._mcp.registerTool('get_url', {
@@ -732,15 +924,24 @@ class ComponentExplorerMcpServer extends Disposable {
             annotations: { readOnlyHint: true },
         }, async (args) => {
             const sessionName = args.sessionName ?? this._defaultSessionName();
-            const session = this._sessions.find(s => s.name === sessionName);
+            let session = this._sessions.find(s => s.name === sessionName);
             if (!session) {
-                // Try to refresh sessions if we don't have the requested session
                 const daemon = await this._waitForDaemon();
                 if (daemon) {
-                    await this._refreshSessions();
+                    try {
+                        await this._refreshSessions();
+                    }
+                    catch (e) {
+                        if (isPipeConnectionError(e)) {
+                            this._handleDisconnect();
+                        }
+                        else {
+                            throw e;
+                        }
+                    }
                 }
-                const refreshedSession = this._sessions.find(s => s.name === sessionName);
-                if (!refreshedSession) {
+                session = this._sessions.find(s => s.name === sessionName);
+                if (!session) {
                     return {
                         content: [{
                                 type: 'text',
@@ -750,8 +951,7 @@ class ComponentExplorerMcpServer extends Disposable {
                     };
                 }
             }
-            const resolved = session ?? this._sessions.find(s => s.name === sessionName);
-            const baseUrl = resolved && !resolved.isLoading ? resolved.serverUrl : undefined;
+            const baseUrl = session && !session.isLoading ? session.serverUrl : undefined;
             if (!baseUrl) {
                 return {
                     content: [{
@@ -788,6 +988,156 @@ class ComponentExplorerMcpServer extends Disposable {
             };
         });
     }
+    _registerCheckStability() {
+        this._mcp.registerTool('check_stability', {
+            description: 'Check rendering stability of fixtures. Each fixture is unmounted, re-mounted, and screenshotted 3 times (~3s per fixture). ' +
+                'Returns results directly if finished within ~10s, otherwise returns a taskId for polling via check_task. ' +
+                'When returning a taskId, includes partial results collected so far.',
+            inputSchema: {
+                fixtureIdPattern: z.string().optional().describe('RegExp to filter fixtures by fixture ID'),
+                labelPattern: z.string().optional().describe('RegExp to filter fixtures by label (matched against inherited labels)'),
+                sessionName: z.string().optional().describe('Session name (defaults to first session)'),
+                sourceTreeId: z.string().optional().describe('Source tree ID (defaults to latest known)'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => this._withDaemon(async (daemon) => {
+            const sessionName = args.sessionName ?? this._defaultSessionName();
+            this._log('debug', { type: 'tool-call', tool: 'check_stability', sessionName, fixtureIdPattern: args.fixtureIdPattern, labelPattern: args.labelPattern });
+            return this._withSourceTreeRetry(async () => {
+                const sourceTreeId = args.sourceTreeId ?? this._sourceTreeId(sessionName);
+                const allFixtures = await daemon.methods.fixtures.list({ sessionName, sourceTreeId });
+                const filtered = this._filterFixtures(allFixtures, args.fixtureIdPattern, args.labelPattern);
+                if ('error' in filtered) {
+                    return { content: [{ type: 'text', text: filtered.error }], isError: true };
+                }
+                const fixtures = filtered.fixtures;
+                this._log('info', { type: 'check-stability-start', total: fixtures.length, filtered: allFixtures.length - fixtures.length });
+                const task = this._taskManager.startTask(async (report, signal) => {
+                    const results = [];
+                    report({ completed: 0, total: fixtures.length, partialResult: results });
+                    for (let i = 0; i < fixtures.length; i++) {
+                        if (signal.aborted) {
+                            break;
+                        }
+                        const fixture = fixtures[i];
+                        this._log('info', { type: 'check-stability-progress', fixtureId: fixture.fixtureId, index: i + 1, total: fixtures.length });
+                        const result = await daemon.methods.screenshots.take({
+                            fixtureId: fixture.fixtureId,
+                            sessionName,
+                            sourceTreeId,
+                            includeImage: false,
+                            stabilityCheck: true,
+                        });
+                        const r = result;
+                        results.push({
+                            fixtureId: fixture.fixtureId,
+                            isStable: r.isStable ?? true,
+                            screenshots: r.stabilityScreenshots?.map(s => ({ hash: s.hash, delayMs: s.delayMs })) ?? [],
+                        });
+                        report({ completed: i + 1, total: fixtures.length, partialResult: results });
+                    }
+                    const stable = results.filter(r => r.isStable).length;
+                    return {
+                        fixtures: results,
+                        summary: { total: results.length, stable, unstable: results.length - stable },
+                    };
+                });
+                const waited = await this._taskManager.waitForTask(task.id, 10_000);
+                if (!waited) {
+                    return { content: [{ type: 'text', text: 'Error: task disappeared' }], isError: true };
+                }
+                if (waited.done) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(waited.result, null, 2) }],
+                    };
+                }
+                const partial = waited.progress.partialResult;
+                this._taskLastReportedIndex.set(task.id, partial.length);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                taskId: task.id,
+                                status: 'running',
+                                progress: { completed: waited.progress.completed, total: waited.progress.total },
+                                elapsedMs: waited.elapsedMs,
+                                results: partial,
+                            }, null, 2),
+                        }],
+                };
+            });
+        }));
+    }
+    _registerCheckTask() {
+        this._mcp.registerTool('check_task', {
+            description: 'Check on a running task. Waits up to ~2s for completion; if still running, returns progress and new results since last check.',
+            inputSchema: {
+                taskId: z.string().describe('The task ID returned by a previous tool call'),
+            },
+            annotations: { readOnlyHint: true },
+        }, async (args) => {
+            const waited = await this._taskManager.waitForTask(args.taskId, 2_000);
+            if (!waited) {
+                this._taskLastReportedIndex.delete(args.taskId);
+                return {
+                    content: [{ type: 'text', text: `Error: No task found with id '${args.taskId}'` }],
+                    isError: true,
+                };
+            }
+            if (waited.done) {
+                const lastIndex = this._taskLastReportedIndex.get(args.taskId) ?? 0;
+                this._taskLastReportedIndex.delete(args.taskId);
+                const fullResult = waited.result;
+                const newResults = fullResult.fixtures.slice(lastIndex);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                status: 'done',
+                                newResults,
+                                summary: fullResult.summary,
+                            }, null, 2),
+                        }],
+                };
+            }
+            const partial = waited.progress.partialResult;
+            const lastIndex = this._taskLastReportedIndex.get(args.taskId) ?? 0;
+            const newResults = partial.slice(lastIndex);
+            this._taskLastReportedIndex.set(args.taskId, partial.length);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            taskId: args.taskId,
+                            status: 'running',
+                            progress: { completed: waited.progress.completed, total: waited.progress.total },
+                            elapsedMs: waited.elapsedMs,
+                            newResults,
+                        }, null, 2),
+                    }],
+            };
+        });
+    }
+    _registerCancelTask() {
+        this._mcp.registerTool('cancel_task', {
+            description: 'Cancel a running task',
+            inputSchema: {
+                taskId: z.string().describe('The task ID to cancel'),
+            },
+        }, async (args) => {
+            const task = this._taskManager.getTask(args.taskId);
+            if (!task) {
+                return {
+                    content: [{ type: 'text', text: `Error: No task found with id '${args.taskId}'` }],
+                    isError: true,
+                };
+            }
+            this._taskManager.removeTask(args.taskId);
+            return {
+                content: [{ type: 'text', text: `Task '${args.taskId}' cancelled.` }],
+            };
+        });
+    }
 }
 
 export { ComponentExplorerMcpServer, DaemonConnection };