fix: address remaining code review findings (H2/H3/H4, M2-M6, L14/L18/N3)

- Prevent concurrent state mutation by processing file updates sequentially
- Add error handling to command handlers and scanAndSendFileTree
- Add keyboard navigation (arrow keys, Home/End) to overflow menu dropdown
- Fix DashboardViewProvider disposal leak via onDidDispose cleanup
- Normalize path separators before includes() checks for cross-platform reliability
- Fix stale closure in story-detail-view useEffect dependencies
- Add aria-selected and aria-expanded to file tree items
- Cap error array at 50 entries in state-manager collectError
- Use node:path import for consistency

Author: Vincent M.

src/extension/extension.ts

@@ -3,6 +3,11 @@ import { BmadDetector, FileWatcher, StateManager, WorkflowDiscoveryService } fro
 import { DashboardViewProvider } from './providers/dashboard-view-provider';
 import { EditorPanelProvider } from './providers/editor-panel-provider';
 
+function showCommandError(action: string, err: unknown): Thenable<string | undefined> {
+  const msg = err instanceof Error ? err.message : String(err);
+  return vscode.window.showErrorMessage(`BMAD ${action} failed: ${msg}`);
+}
+
 export async function activate(context: vscode.ExtensionContext): Promise<void> {
   // Detect BMAD project in current workspace
   const detector = new BmadDetector();
@@ -32,11 +37,19 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
 
     context.subscriptions.push(
       vscode.window.registerWebviewViewProvider(DashboardViewProvider.viewType, dashboardProvider),
-      vscode.commands.registerCommand('bmad.refresh', () => {
-        void stateManager.refresh();
+      vscode.commands.registerCommand('bmad.refresh', async () => {
+        try {
+          await stateManager.refresh();
+        } catch (err) {
+          void showCommandError('refresh', err);
+        }
       }),
       vscode.commands.registerCommand('bmad.openEditorPanel', () => {
-        EditorPanelProvider.createOrShow(context.extensionUri, stateManager);
+        try {
+          EditorPanelProvider.createOrShow(context.extensionUri, stateManager);
+        } catch (err) {
+          void showCommandError('open panel', err);
+        }
       }),
       // Dispose editor panel on extension deactivation (singleton may be open)
       { dispose: () => EditorPanelProvider.disposePanel() },

src/extension/parsers/epic-parser.ts

@@ -83,8 +83,7 @@ function parseStoryEntries(content: string): EpicStoryEntry[] {
     const current = matches[i];
     // Calculate end boundary for this story's content section.
     // For the last story, use end of content. For others, use the start of the next header.
-    const nextIndex =
-      i + 1 < matches.length ? matches[i + 1].startIndex : content.length;
+    const nextIndex = i + 1 < matches.length ? matches[i + 1].startIndex : content.length;
 
     // Get content between this story header and the next (or end)
     const storyContent = content.slice(current.index, nextIndex);

src/extension/providers/dashboard-view-provider.ts

@@ -78,6 +78,14 @@ export class DashboardViewProvider implements vscode.WebviewViewProvider {
         this.disposables
       );
     }
+
+    // Clean up disposables when the webview is disposed
+    webviewView.onDidDispose(() => {
+      for (const d of this.disposables) {
+        d.dispose();
+      }
+      this.disposables.length = 0;
+    });
   }
 
   /**

src/extension/providers/editor-panel-provider.ts

@@ -1,5 +1,5 @@
 import * as vscode from 'vscode';
-import * as path from 'path';
+import * as path from 'node:path';
 import matter from 'gray-matter';
 import type { StateManager } from '../services/state-manager';
 import {
@@ -169,9 +169,14 @@ export class EditorPanelProvider implements vscode.Disposable {
    * Scan document library directories and send the file tree to the webview.
    */
   private async scanAndSendFileTree(): Promise<void> {
-    const scanner = new FileTreeScanner();
-    const roots = await scanner.scan();
-    void this.panel.webview.postMessage(createFileTreeMessage(roots));
+    try {
+      const scanner = new FileTreeScanner();
+      const roots = await scanner.scan();
+      void this.panel.webview.postMessage(createFileTreeMessage(roots));
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.debug('[BMAD] Failed to scan file tree:', err);
+    }
   }
 
   public dispose(): void {

src/extension/services/state-manager.ts

@@ -23,6 +23,7 @@ import { createInitialDashboardState, isStoryKey, isEpicKey } from '../../shared
  *   'readme.md' → false (doesn't match X-Y-name pattern)
  */
 const STORY_FILE_REGEX = /^\d+-\d+[a-z]?-[\w-]+\.md$/;
+const MAX_STORED_ERRORS = 50;
 
 /**
  * Service for managing aggregated BMAD dashboard state.
@@ -516,14 +517,15 @@ export class StateManager implements vscode.Disposable {
       this.removeFromState(filePath);
     }
 
-    // Process creates/changes in parallel
+    // Process creates/changes sequentially to avoid concurrent state mutation
     const updateChanges = Array.from(event.changes.entries()).filter(
       ([, changeType]) => changeType !== 'delete'
     );
-    const updatePromises = updateChanges.map(async ([filePath]) =>
-      this.handleFileUpdate(filePath, paths.outputRoot!)
-    );
-    await Promise.all(updatePromises);
+    for (const [filePath] of updateChanges) {
+      // Sequential processing is intentional — prevents concurrent state mutation
+      // eslint-disable-next-line no-await-in-loop
+      await this.handleFileUpdate(filePath, paths.outputRoot);
+    }
 
     this.determineCurrentStory();
     this.buildStorySummaries();
@@ -543,11 +545,13 @@ export class StateManager implements vscode.Disposable {
    * Handle a file update (create or change).
    */
   private async handleFileUpdate(filePath: string, outputRoot: vscode.Uri): Promise<void> {
-    const fileName = this.getFileName(filePath);
+    // Normalize path separators for reliable matching on all platforms
+    const normalizedPath = filePath.replace(/\\/g, '/');
+    const fileName = normalizedPath.split('/').pop()!;
 
     if (fileName === 'sprint-status.yaml') {
       await this.parseSprintStatus(outputRoot);
-    } else if (filePath.includes('planning-artifacts') && fileName === 'epics.md') {
+    } else if (normalizedPath.includes('planning-artifacts') && fileName === 'epics.md') {
       await this.parseEpics(outputRoot);
       this._state = {
         ...this._state,
@@ -557,14 +561,14 @@ export class StateManager implements vscode.Disposable {
         },
       };
     } else if (
-      filePath.includes('planning-artifacts') &&
+      normalizedPath.includes('planning-artifacts') &&
       (fileName === 'prd.md' ||
         fileName === 'architecture.md' ||
         this.isProductBriefFile(fileName) ||
         this.isReadinessReportFile(fileName))
     ) {
       await this.detectPlanningArtifacts(outputRoot);
-    } else if (filePath.includes('implementation-artifacts') && this.isStoryFile(fileName)) {
+    } else if (normalizedPath.includes('implementation-artifacts') && this.isStoryFile(fileName)) {
       await this.parseStoryFile(vscode.Uri.file(filePath));
     }
     // Other files are ignored (not relevant to BMAD dashboard)
@@ -670,8 +674,8 @@ export class StateManager implements vscode.Disposable {
       ? this._state.errors.filter((e) => e.filePath !== error.filePath)
       : this._state.errors;
 
-    // Add the new error
-    this._state = { ...this._state, errors: [...errors, error] };
+    // Add the new error (cap to prevent unbounded growth)
+    this._state = { ...this._state, errors: [...errors, error].slice(-MAX_STORED_ERRORS) };
   }
 
   /**

src/webviews/dashboard/components/header-toolbar.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useRef, useEffect, useCallback } from 'react';
+import React, { useState, useRef, useEffect, useCallback, type KeyboardEvent } from 'react';
 import { HelpCircle, EllipsisVertical, RefreshCw, Play, PanelRight } from 'lucide-react';
 import { useWorkflows } from '../store';
 import { useVSCodeApi } from '../../shared/hooks';
@@ -56,13 +56,51 @@ export function HeaderToolbar(): React.ReactElement {
   // Escape key dismiss
   useEffect(() => {
     if (!isOpen) return;
-    const handleEscape = (e: KeyboardEvent) => {
+    const handleEscape = (e: globalThis.KeyboardEvent) => {
       if (e.key === 'Escape') setIsOpen(false);
     };
     document.addEventListener('keydown', handleEscape);
     return () => document.removeEventListener('keydown', handleEscape);
   }, [isOpen]);
 
+  // Focus first menu item when menu opens
+  const menuItemsRef = useRef<(HTMLButtonElement | null)[]>([]);
+  useEffect(() => {
+    if (isOpen) {
+      menuItemsRef.current[0]?.focus();
+    }
+  }, [isOpen]);
+
+  // Arrow key navigation for menu items
+  const handleMenuKeyDown = useCallback((e: KeyboardEvent<HTMLDivElement>) => {
+    const items = menuItemsRef.current.filter(Boolean) as HTMLButtonElement[];
+    const currentIndex = items.indexOf(document.activeElement as HTMLButtonElement);
+    let nextIndex = -1;
+
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        nextIndex = currentIndex + 1 >= items.length ? 0 : currentIndex + 1;
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        nextIndex = currentIndex - 1 < 0 ? items.length - 1 : currentIndex - 1;
+        break;
+      case 'Home':
+        e.preventDefault();
+        nextIndex = 0;
+        break;
+      case 'End':
+        e.preventDefault();
+        nextIndex = items.length - 1;
+        break;
+    }
+
+    if (nextIndex >= 0) {
+      items[nextIndex].focus();
+    }
+  }, []);
+
   const iconButtonClass =
     'rounded p-1 text-[var(--vscode-descriptionForeground)] hover:text-[var(--vscode-foreground)] hover:bg-[var(--vscode-toolbar-hoverBackground)] focus:ring-1 focus:ring-[var(--vscode-focusBorder)] focus:outline-none';
 
@@ -96,11 +134,16 @@ export function HeaderToolbar(): React.ReactElement {
           <div
             role="menu"
             data-testid="overflow-menu-dropdown"
+            onKeyDown={handleMenuKeyDown}
             className="animate-expand-in absolute top-full right-0 z-10 mt-1 min-w-[160px] rounded border border-[var(--vscode-menu-border)] bg-[var(--vscode-menu-background)] py-1 shadow-md"
           >
             <button
+              ref={(el) => {
+                menuItemsRef.current[0] = el;
+              }}
               role="menuitem"
               type="button"
+              tabIndex={-1}
               data-testid="overflow-menu-open-panel"
               onClick={handleOpenPanel}
               className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs text-[var(--vscode-menu-foreground)] hover:bg-[var(--vscode-menu-selectionBackground)]"
@@ -109,20 +152,28 @@ export function HeaderToolbar(): React.ReactElement {
               Open Tab View
             </button>
             <button
+              ref={(el) => {
+                menuItemsRef.current[1] = el;
+              }}
               role="menuitem"
               type="button"
+              tabIndex={-1}
               data-testid="overflow-menu-refresh"
               onClick={handleRefresh}
               className="flex w-full items-center gap-2 px-3 py-1.5 text-left text-xs text-[var(--vscode-menu-foreground)] hover:bg-[var(--vscode-menu-selectionBackground)]"
             >
               <RefreshCw size={12} />
               Refresh
             </button>
-            {workflows.map((workflow) => (
+            {workflows.map((workflow, index) => (
               <button
+                ref={(el) => {
+                  menuItemsRef.current[index + 2] = el;
+                }}
                 key={workflow.id}
                 role="menuitem"
                 type="button"
+                tabIndex={-1}
                 data-testid={`overflow-menu-workflow-${workflow.id}`}
                 onClick={() => handleWorkflowClick(workflow.command)}
                 title={workflow.description}

src/webviews/editor-panel/components/file-tree.tsx

@@ -125,7 +125,11 @@ function FileTreeItem({
   );
 
   return (
-    <div role="treeitem">
+    <div
+      role="treeitem"
+      aria-selected={isSelected}
+      aria-expanded={isDirectory ? isExpanded : undefined}
+    >
       <button
         data-testid={`file-tree-item-${node.path}`}
         className="flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-left hover:bg-[var(--vscode-list-hoverBackground)]"

src/webviews/editor-panel/views/story-detail-view.tsx

@@ -55,18 +55,26 @@ export function StoryDetailView(): React.ReactElement {
   );
 
   // Load story detail on mount when needed
+  const storyDetailKey = storyDetail?.key;
   useEffect(() => {
     if (!summary?.filePath) return;
     // If we already have the correct story loaded, skip
-    if (storyDetail?.key === storyKey) return;
+    if (storyDetailKey === storyKey) return;
 
     setStoryDetailLoading(true);
     vscodeApi.postMessage(createRequestDocumentContentMessage(summary.filePath));
 
     return () => {
       clearStoryDetail();
     };
-  }, [storyKey, summary?.filePath]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [
+    storyKey,
+    summary?.filePath,
+    storyDetailKey,
+    setStoryDetailLoading,
+    vscodeApi,
+    clearStoryDetail,
+  ]);
 
   if (!storyKey) {
     return (