feat(tests): implement test runner functionality with API integration

- Added Test Runner Service to manage test execution processes for worktrees.
- Introduced endpoints for starting and stopping tests, and retrieving test logs.
- Created UI components for displaying test logs and managing test sessions.
- Integrated test runner events for real-time updates in the UI.
- Updated project settings to include configurable test commands.

This enhancement allows users to run tests directly from the UI, view logs in real-time, and manage test sessions effectively.

apps/server/src/index.ts

@@ -83,6 +83,7 @@ import { createNotificationsRoutes } from './routes/notifications/index.js';
 import { getNotificationService } from './services/notification-service.js';
 import { createEventHistoryRoutes } from './routes/event-history/index.js';
 import { getEventHistoryService } from './services/event-history-service.js';
+import { getTestRunnerService } from './services/test-runner-service.js';
 
 // Load environment variables
 dotenv.config();
@@ -248,6 +249,10 @@ notificationService.setEventEmitter(events);
 // Initialize Event History Service
 const eventHistoryService = getEventHistoryService();
 
+// Initialize Test Runner Service with event emitter for real-time test output streaming
+const testRunnerService = getTestRunnerService();
+testRunnerService.setEventEmitter(events);
+
 // Initialize Event Hook Service for custom event triggers (with history storage)
 eventHookService.initialize(events, settingsService, eventHistoryService, featureLoader);
 

apps/server/src/routes/worktree/index.ts

@@ -42,6 +42,9 @@ import { createStartDevHandler } from './routes/start-dev.js';
 import { createStopDevHandler } from './routes/stop-dev.js';
 import { createListDevServersHandler } from './routes/list-dev-servers.js';
 import { createGetDevServerLogsHandler } from './routes/dev-server-logs.js';
+import { createStartTestsHandler } from './routes/start-tests.js';
+import { createStopTestsHandler } from './routes/stop-tests.js';
+import { createGetTestLogsHandler } from './routes/test-logs.js';
 import {
   createGetInitScriptHandler,
   createPutInitScriptHandler,
@@ -140,6 +143,15 @@ export function createWorktreeRoutes(
     createGetDevServerLogsHandler()
   );
 
+  // Test runner routes
+  router.post(
+    '/start-tests',
+    validatePathParams('worktreePath'),
+    createStartTestsHandler(settingsService)
+  );
+  router.post('/stop-tests', createStopTestsHandler());
+  router.get('/test-logs', createGetTestLogsHandler());
+
   // Init script routes
   router.get('/init-script', createGetInitScriptHandler());
   router.put('/init-script', validatePathParams('projectPath'), createPutInitScriptHandler());

apps/server/src/routes/worktree/routes/start-tests.ts

@@ -0,0 +1,89 @@
+/**
+ * POST /start-tests endpoint - Start tests for a worktree
+ *
+ * Runs the test command configured in project settings.
+ * If no testCommand is configured, returns an error.
+ */
+
+import type { Request, Response } from 'express';
+import type { SettingsService } from '../../../services/settings-service.js';
+import { getTestRunnerService } from '../../../services/test-runner-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createStartTestsHandler(settingsService?: SettingsService) {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { worktreePath, projectPath, testFile } = req.body as {
+        worktreePath: string;
+        projectPath?: string;
+        testFile?: string;
+      };
+
+      if (!worktreePath) {
+        res.status(400).json({
+          success: false,
+          error: 'worktreePath is required',
+        });
+        return;
+      }
+
+      // Get project settings to find the test command
+      // Use projectPath if provided, otherwise use worktreePath
+      const settingsPath = projectPath || worktreePath;
+
+      if (!settingsService) {
+        res.status(500).json({
+          success: false,
+          error: 'Settings service not available',
+        });
+        return;
+      }
+
+      const projectSettings = await settingsService.getProjectSettings(settingsPath);
+      const testCommand = projectSettings?.testCommand;
+
+      // Debug logging
+      console.log('[StartTests] settingsPath:', settingsPath);
+      console.log('[StartTests] projectSettings:', JSON.stringify(projectSettings, null, 2));
+      console.log('[StartTests] testCommand:', testCommand);
+      console.log('[StartTests] testCommand type:', typeof testCommand);
+
+      if (!testCommand) {
+        res.status(400).json({
+          success: false,
+          error:
+            'No test command configured. Please configure a test command in Project Settings > Testing Configuration.',
+        });
+        return;
+      }
+
+      const testRunnerService = getTestRunnerService();
+      const result = await testRunnerService.startTests(worktreePath, {
+        command: testCommand,
+        testFile,
+      });
+
+      if (result.success && result.result) {
+        res.json({
+          success: true,
+          result: {
+            sessionId: result.result.sessionId,
+            worktreePath: result.result.worktreePath,
+            command: result.result.command,
+            status: result.result.status,
+            testFile: result.result.testFile,
+            message: result.result.message,
+          },
+        });
+      } else {
+        res.status(400).json({
+          success: false,
+          error: result.error || 'Failed to start tests',
+        });
+      }
+    } catch (error) {
+      logError(error, 'Start tests failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/worktree/routes/stop-tests.ts

@@ -0,0 +1,49 @@
+/**
+ * POST /stop-tests endpoint - Stop a running test session
+ *
+ * Stops the test runner process for a specific session,
+ * cancelling any ongoing tests and freeing up resources.
+ */
+
+import type { Request, Response } from 'express';
+import { getTestRunnerService } from '../../../services/test-runner-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createStopTestsHandler() {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { sessionId } = req.body as {
+        sessionId: string;
+      };
+
+      if (!sessionId) {
+        res.status(400).json({
+          success: false,
+          error: 'sessionId is required',
+        });
+        return;
+      }
+
+      const testRunnerService = getTestRunnerService();
+      const result = await testRunnerService.stopTests(sessionId);
+
+      if (result.success && result.result) {
+        res.json({
+          success: true,
+          result: {
+            sessionId: result.result.sessionId,
+            message: result.result.message,
+          },
+        });
+      } else {
+        res.status(400).json({
+          success: false,
+          error: result.error || 'Failed to stop tests',
+        });
+      }
+    } catch (error) {
+      logError(error, 'Stop tests failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/routes/worktree/routes/test-logs.ts

@@ -0,0 +1,133 @@
+/**
+ * GET /test-logs endpoint - Get buffered logs for a test runner session
+ *
+ * Returns the scrollback buffer containing historical log output for a test run.
+ * Used by clients to populate the log panel on initial connection
+ * before subscribing to real-time updates via WebSocket.
+ *
+ * Query parameters:
+ * - worktreePath: Path to the worktree (optional if sessionId provided)
+ * - sessionId: Specific test session ID (optional, uses active session if not provided)
+ */
+
+import type { Request, Response } from 'express';
+import { getTestRunnerService } from '../../../services/test-runner-service.js';
+import { getErrorMessage, logError } from '../common.js';
+
+export function createGetTestLogsHandler() {
+  return async (req: Request, res: Response): Promise<void> => {
+    try {
+      const { worktreePath, sessionId } = req.query as {
+        worktreePath?: string;
+        sessionId?: string;
+      };
+
+      const testRunnerService = getTestRunnerService();
+
+      // If sessionId is provided, get logs for that specific session
+      if (sessionId) {
+        const result = testRunnerService.getSessionOutput(sessionId);
+
+        if (result.success && result.result) {
+          const session = testRunnerService.getSession(sessionId);
+          res.json({
+            success: true,
+            result: {
+              sessionId: result.result.sessionId,
+              worktreePath: session?.worktreePath,
+              command: session?.command,
+              status: result.result.status,
+              testFile: session?.testFile,
+              logs: result.result.output,
+              startedAt: result.result.startedAt,
+              finishedAt: result.result.finishedAt,
+              exitCode: session?.exitCode ?? null,
+            },
+          });
+        } else {
+          res.status(404).json({
+            success: false,
+            error: result.error || 'Failed to get test logs',
+          });
+        }
+        return;
+      }
+
+      // If worktreePath is provided, get logs for the active session
+      if (worktreePath) {
+        const activeSession = testRunnerService.getActiveSession(worktreePath);
+
+        if (activeSession) {
+          const result = testRunnerService.getSessionOutput(activeSession.id);
+
+          if (result.success && result.result) {
+            res.json({
+              success: true,
+              result: {
+                sessionId: activeSession.id,
+                worktreePath: activeSession.worktreePath,
+                command: activeSession.command,
+                status: result.result.status,
+                testFile: activeSession.testFile,
+                logs: result.result.output,
+                startedAt: result.result.startedAt,
+                finishedAt: result.result.finishedAt,
+                exitCode: activeSession.exitCode,
+              },
+            });
+          } else {
+            res.status(404).json({
+              success: false,
+              error: result.error || 'Failed to get test logs',
+            });
+          }
+        } else {
+          // No active session - check for most recent session for this worktree
+          const sessions = testRunnerService.listSessions(worktreePath);
+          if (sessions.result.sessions.length > 0) {
+            // Get the most recent session (list is not sorted, so find it)
+            const mostRecent = sessions.result.sessions.reduce((latest, current) => {
+              const latestTime = new Date(latest.startedAt).getTime();
+              const currentTime = new Date(current.startedAt).getTime();
+              return currentTime > latestTime ? current : latest;
+            });
+
+            const result = testRunnerService.getSessionOutput(mostRecent.sessionId);
+            if (result.success && result.result) {
+              res.json({
+                success: true,
+                result: {
+                  sessionId: mostRecent.sessionId,
+                  worktreePath: mostRecent.worktreePath,
+                  command: mostRecent.command,
+                  status: result.result.status,
+                  testFile: mostRecent.testFile,
+                  logs: result.result.output,
+                  startedAt: result.result.startedAt,
+                  finishedAt: result.result.finishedAt,
+                  exitCode: mostRecent.exitCode,
+                },
+              });
+              return;
+            }
+          }
+
+          res.status(404).json({
+            success: false,
+            error: 'No test sessions found for this worktree',
+          });
+        }
+        return;
+      }
+
+      // Neither sessionId nor worktreePath provided
+      res.status(400).json({
+        success: false,
+        error: 'Either worktreePath or sessionId query parameter is required',
+      });
+    } catch (error) {
+      logError(error, 'Get test logs failed');
+      res.status(500).json({ success: false, error: getErrorMessage(error) });
+    }
+  };
+}

apps/server/src/services/test-runner-service.ts

@@ -0,0 +1,666 @@
+/**
+ * Test Runner Service
+ *
+ * Manages test execution processes for git worktrees.
+ * Runs user-configured test commands with output streaming.
+ *
+ * Features:
+ * - Process management with graceful shutdown
+ * - Output buffering and throttling for WebSocket streaming
+ * - Support for running all tests or specific files
+ * - Cross-platform process cleanup (Windows/Unix)
+ */
+
+import { spawn, execSync, type ChildProcess } from 'child_process';
+import * as secureFs from '../lib/secure-fs.js';
+import { createLogger } from '@automaker/utils';
+import type { EventEmitter } from '../lib/events.js';
+
+const logger = createLogger('TestRunnerService');
+
+// Maximum scrollback buffer size (characters)
+const MAX_SCROLLBACK_SIZE = 50000; // ~50KB per test run
+
+// Throttle output to prevent overwhelming WebSocket under heavy load
+// Note: Too aggressive throttling (< 50ms) can cause memory issues and UI crashes
+// due to rapid React state updates and string concatenation overhead
+const OUTPUT_THROTTLE_MS = 100; // ~10fps - balances responsiveness with stability
+const OUTPUT_BATCH_SIZE = 8192; // Larger batch size to reduce event frequency
+
+/**
+ * Status of a test run
+ */
+export type TestRunStatus = 'pending' | 'running' | 'passed' | 'failed' | 'cancelled' | 'error';
+
+/**
+ * Information about an active test run session
+ */
+export interface TestRunSession {
+  /** Unique identifier for this test run */
+  id: string;
+  /** Path to the worktree where tests are running */
+  worktreePath: string;
+  /** The command being run */
+  command: string;
+  /** The spawned child process */
+  process: ChildProcess | null;
+  /** When the test run started */
+  startedAt: Date;
+  /** When the test run finished (if completed) */
+  finishedAt: Date | null;
+  /** Current status of the test run */
+  status: TestRunStatus;
+  /** Exit code from the process (if completed) */
+  exitCode: number | null;
+  /** Specific test file being run (optional) */
+  testFile?: string;
+  /** Scrollback buffer for log history (replay on reconnect) */
+  scrollbackBuffer: string;
+  /** Pending output to be flushed to subscribers */
+  outputBuffer: string;
+  /** Throttle timer for batching output */
+  flushTimeout: NodeJS.Timeout | null;
+  /** Flag to indicate session is stopping (prevents output after stop) */
+  stopping: boolean;
+}
+
+/**
+ * Result of a test run operation
+ */
+export interface TestRunResult {
+  success: boolean;
+  result?: {
+    sessionId: string;
+    worktreePath: string;
+    command: string;
+    status: TestRunStatus;
+    testFile?: string;
+    message: string;
+  };
+  error?: string;
+}
+
+/**
+ * Test Runner Service class
+ * Manages test execution processes across worktrees
+ */
+class TestRunnerService {
+  private sessions: Map<string, TestRunSession> = new Map();
+  private emitter: EventEmitter | null = null;
+
+  /**
+   * Set the event emitter for streaming log events
+   * Called during service initialization with the global event emitter
+   */
+  setEventEmitter(emitter: EventEmitter): void {
+    this.emitter = emitter;
+  }
+
+  /**
+   * Helper to check if a file exists using secureFs
+   */
+  private async fileExists(filePath: string): Promise<boolean> {
+    try {
+      await secureFs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Append data to scrollback buffer with size limit enforcement
+   * Evicts oldest data when buffer exceeds MAX_SCROLLBACK_SIZE
+   */
+  private appendToScrollback(session: TestRunSession, data: string): void {
+    session.scrollbackBuffer += data;
+    if (session.scrollbackBuffer.length > MAX_SCROLLBACK_SIZE) {
+      session.scrollbackBuffer = session.scrollbackBuffer.slice(-MAX_SCROLLBACK_SIZE);
+    }
+  }
+
+  /**
+   * Flush buffered output to WebSocket subscribers
+   * Sends batched output to prevent overwhelming clients under heavy load
+   */
+  private flushOutput(session: TestRunSession): void {
+    // Skip flush if session is stopping or buffer is empty
+    if (session.stopping || session.outputBuffer.length === 0) {
+      session.flushTimeout = null;
+      return;
+    }
+
+    let dataToSend = session.outputBuffer;
+    if (dataToSend.length > OUTPUT_BATCH_SIZE) {
+      // Send in batches if buffer is large
+      dataToSend = session.outputBuffer.slice(0, OUTPUT_BATCH_SIZE);
+      session.outputBuffer = session.outputBuffer.slice(OUTPUT_BATCH_SIZE);
+      // Schedule another flush for remaining data
+      session.flushTimeout = setTimeout(() => this.flushOutput(session), OUTPUT_THROTTLE_MS);
+    } else {
+      session.outputBuffer = '';
+      session.flushTimeout = null;
+    }
+
+    // Emit output event for WebSocket streaming
+    if (this.emitter) {
+      this.emitter.emit('test-runner:output', {
+        sessionId: session.id,
+        worktreePath: session.worktreePath,
+        content: dataToSend,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  /**
+   * Handle incoming stdout/stderr data from test process
+   * Buffers data for scrollback replay and schedules throttled emission
+   */
+  private handleProcessOutput(session: TestRunSession, data: Buffer): void {
+    // Skip output if session is stopping
+    if (session.stopping) {
+      return;
+    }
+
+    const content = data.toString();
+
+    // Append to scrollback buffer for replay on reconnect
+    this.appendToScrollback(session, content);
+
+    // Buffer output for throttled live delivery
+    session.outputBuffer += content;
+
+    // Schedule flush if not already scheduled
+    if (!session.flushTimeout) {
+      session.flushTimeout = setTimeout(() => this.flushOutput(session), OUTPUT_THROTTLE_MS);
+    }
+
+    // Also log for debugging (existing behavior)
+    logger.debug(`[${session.id}] ${content.trim()}`);
+  }
+
+  /**
+   * Kill any process running (platform-specific cleanup)
+   */
+  private killProcessTree(pid: number): void {
+    try {
+      if (process.platform === 'win32') {
+        // Windows: use taskkill to kill process tree
+        execSync(`taskkill /F /T /PID ${pid}`, { stdio: 'ignore' });
+      } else {
+        // Unix: kill the process group
+        try {
+          process.kill(-pid, 'SIGTERM');
+        } catch {
+          // Fallback to killing just the process
+          process.kill(pid, 'SIGTERM');
+        }
+      }
+    } catch (error) {
+      logger.debug(`Error killing process ${pid}:`, error);
+    }
+  }
+
+  /**
+   * Generate a unique session ID
+   */
+  private generateSessionId(): string {
+    return `test-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+
+  /**
+   * Start tests in a worktree using the provided command
+   *
+   * @param worktreePath - Path to the worktree where tests should run
+   * @param options - Configuration for the test run
+   * @returns TestRunResult with session info or error
+   */
+  async startTests(
+    worktreePath: string,
+    options: {
+      command: string;
+      testFile?: string;
+    }
+  ): Promise<TestRunResult> {
+    const { command, testFile } = options;
+
+    // Check if already running
+    const existingSession = this.getActiveSession(worktreePath);
+    if (existingSession) {
+      return {
+        success: false,
+        error: `Tests are already running for this worktree (session: ${existingSession.id})`,
+      };
+    }
+
+    // Verify the worktree exists
+    if (!(await this.fileExists(worktreePath))) {
+      return {
+        success: false,
+        error: `Worktree path does not exist: ${worktreePath}`,
+      };
+    }
+
+    if (!command) {
+      return {
+        success: false,
+        error: 'No test command provided',
+      };
+    }
+
+    // Build the final command (append test file if specified)
+    let finalCommand = command;
+    if (testFile) {
+      // Append the test file to the command
+      // Most test runners support: command -- file or command file
+      finalCommand = `${command} -- ${testFile}`;
+    }
+
+    // Parse command into cmd and args (shell execution)
+    // We use shell: true to support complex commands like "npm run test:server"
+    logger.info(`Starting tests in ${worktreePath}`);
+    logger.info(`Command: ${finalCommand}`);
+
+    // Create session
+    const sessionId = this.generateSessionId();
+    const session: TestRunSession = {
+      id: sessionId,
+      worktreePath,
+      command: finalCommand,
+      process: null,
+      startedAt: new Date(),
+      finishedAt: null,
+      status: 'pending',
+      exitCode: null,
+      testFile,
+      scrollbackBuffer: '',
+      outputBuffer: '',
+      flushTimeout: null,
+      stopping: false,
+    };
+
+    // Spawn the test process using shell
+    const env = {
+      ...process.env,
+      FORCE_COLOR: '1',
+      COLORTERM: 'truecolor',
+      TERM: 'xterm-256color',
+      CI: 'true', // Helps some test runners format output better
+    };
+
+    const testProcess = spawn(finalCommand, [], {
+      cwd: worktreePath,
+      env,
+      shell: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32', // Use process groups on Unix for cleanup
+    });
+
+    session.process = testProcess;
+    session.status = 'running';
+
+    // Track if process failed early
+    const status = { error: null as string | null, exited: false };
+
+    // Helper to clean up resources and emit events
+    const cleanupAndFinish = (
+      exitCode: number | null,
+      finalStatus: TestRunStatus,
+      errorMessage?: string
+    ) => {
+      session.finishedAt = new Date();
+      session.exitCode = exitCode;
+      session.status = finalStatus;
+
+      if (session.flushTimeout) {
+        clearTimeout(session.flushTimeout);
+        session.flushTimeout = null;
+      }
+
+      // Flush any remaining output
+      if (session.outputBuffer.length > 0 && this.emitter && !session.stopping) {
+        this.emitter.emit('test-runner:output', {
+          sessionId: session.id,
+          worktreePath: session.worktreePath,
+          content: session.outputBuffer,
+          timestamp: new Date().toISOString(),
+        });
+        session.outputBuffer = '';
+      }
+
+      // Emit completed event
+      if (this.emitter && !session.stopping) {
+        this.emitter.emit('test-runner:completed', {
+          sessionId: session.id,
+          worktreePath: session.worktreePath,
+          command: session.command,
+          status: finalStatus,
+          exitCode,
+          error: errorMessage,
+          duration: session.finishedAt.getTime() - session.startedAt.getTime(),
+          timestamp: new Date().toISOString(),
+        });
+      }
+    };
+
+    // Capture stdout
+    if (testProcess.stdout) {
+      testProcess.stdout.on('data', (data: Buffer) => {
+        this.handleProcessOutput(session, data);
+      });
+    }
+
+    // Capture stderr
+    if (testProcess.stderr) {
+      testProcess.stderr.on('data', (data: Buffer) => {
+        this.handleProcessOutput(session, data);
+      });
+    }
+
+    testProcess.on('error', (error) => {
+      logger.error(`Process error for ${sessionId}:`, error);
+      status.error = error.message;
+      cleanupAndFinish(null, 'error', error.message);
+    });
+
+    testProcess.on('exit', (code) => {
+      logger.info(`Test process for ${worktreePath} exited with code ${code}`);
+      status.exited = true;
+
+      // Determine final status based on exit code
+      let finalStatus: TestRunStatus;
+      if (session.stopping) {
+        finalStatus = 'cancelled';
+      } else if (code === 0) {
+        finalStatus = 'passed';
+      } else {
+        finalStatus = 'failed';
+      }
+
+      cleanupAndFinish(code, finalStatus);
+    });
+
+    // Store session
+    this.sessions.set(sessionId, session);
+
+    // Wait a moment to see if the process fails immediately
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    if (status.error) {
+      return {
+        success: false,
+        error: `Failed to start tests: ${status.error}`,
+      };
+    }
+
+    if (status.exited) {
+      // Process already exited - check if it was immediate failure
+      const exitedSession = this.sessions.get(sessionId);
+      if (exitedSession && exitedSession.status === 'error') {
+        return {
+          success: false,
+          error: `Test process exited immediately. Check output for details.`,
+        };
+      }
+    }
+
+    // Emit started event
+    if (this.emitter) {
+      this.emitter.emit('test-runner:started', {
+        sessionId,
+        worktreePath,
+        command: finalCommand,
+        testFile,
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    return {
+      success: true,
+      result: {
+        sessionId,
+        worktreePath,
+        command: finalCommand,
+        status: 'running',
+        testFile,
+        message: `Tests started: ${finalCommand}`,
+      },
+    };
+  }
+
+  /**
+   * Stop a running test session
+   *
+   * @param sessionId - The ID of the test session to stop
+   * @returns Result with success status and message
+   */
+  async stopTests(sessionId: string): Promise<{
+    success: boolean;
+    result?: { sessionId: string; message: string };
+    error?: string;
+  }> {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        error: `Test session not found: ${sessionId}`,
+      };
+    }
+
+    if (session.status !== 'running') {
+      return {
+        success: true,
+        result: {
+          sessionId,
+          message: `Tests already finished (status: ${session.status})`,
+        },
+      };
+    }
+
+    logger.info(`Cancelling test session ${sessionId}`);
+
+    // Mark as stopping to prevent further output events
+    session.stopping = true;
+
+    // Clean up flush timeout
+    if (session.flushTimeout) {
+      clearTimeout(session.flushTimeout);
+      session.flushTimeout = null;
+    }
+
+    // Kill the process
+    if (session.process && !session.process.killed && session.process.pid) {
+      this.killProcessTree(session.process.pid);
+    }
+
+    session.status = 'cancelled';
+    session.finishedAt = new Date();
+
+    // Emit cancelled event
+    if (this.emitter) {
+      this.emitter.emit('test-runner:completed', {
+        sessionId,
+        worktreePath: session.worktreePath,
+        command: session.command,
+        status: 'cancelled',
+        exitCode: null,
+        duration: session.finishedAt.getTime() - session.startedAt.getTime(),
+        timestamp: new Date().toISOString(),
+      });
+    }
+
+    return {
+      success: true,
+      result: {
+        sessionId,
+        message: 'Test run cancelled',
+      },
+    };
+  }
+
+  /**
+   * Get the active test session for a worktree
+   */
+  getActiveSession(worktreePath: string): TestRunSession | undefined {
+    for (const session of this.sessions.values()) {
+      if (session.worktreePath === worktreePath && session.status === 'running') {
+        return session;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Get a test session by ID
+   */
+  getSession(sessionId: string): TestRunSession | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  /**
+   * Get buffered output for a test session
+   */
+  getSessionOutput(sessionId: string): {
+    success: boolean;
+    result?: {
+      sessionId: string;
+      output: string;
+      status: TestRunStatus;
+      startedAt: string;
+      finishedAt: string | null;
+    };
+    error?: string;
+  } {
+    const session = this.sessions.get(sessionId);
+
+    if (!session) {
+      return {
+        success: false,
+        error: `Test session not found: ${sessionId}`,
+      };
+    }
+
+    return {
+      success: true,
+      result: {
+        sessionId,
+        output: session.scrollbackBuffer,
+        status: session.status,
+        startedAt: session.startedAt.toISOString(),
+        finishedAt: session.finishedAt?.toISOString() || null,
+      },
+    };
+  }
+
+  /**
+   * List all test sessions (optionally filter by worktree)
+   */
+  listSessions(worktreePath?: string): {
+    success: boolean;
+    result: {
+      sessions: Array<{
+        sessionId: string;
+        worktreePath: string;
+        command: string;
+        status: TestRunStatus;
+        testFile?: string;
+        startedAt: string;
+        finishedAt: string | null;
+        exitCode: number | null;
+      }>;
+    };
+  } {
+    let sessions = Array.from(this.sessions.values());
+
+    if (worktreePath) {
+      sessions = sessions.filter((s) => s.worktreePath === worktreePath);
+    }
+
+    return {
+      success: true,
+      result: {
+        sessions: sessions.map((s) => ({
+          sessionId: s.id,
+          worktreePath: s.worktreePath,
+          command: s.command,
+          status: s.status,
+          testFile: s.testFile,
+          startedAt: s.startedAt.toISOString(),
+          finishedAt: s.finishedAt?.toISOString() || null,
+          exitCode: s.exitCode,
+        })),
+      },
+    };
+  }
+
+  /**
+   * Check if a worktree has an active test run
+   */
+  isRunning(worktreePath: string): boolean {
+    return this.getActiveSession(worktreePath) !== undefined;
+  }
+
+  /**
+   * Clean up old completed sessions (keep only recent ones)
+   */
+  cleanupOldSessions(maxAgeMs: number = 30 * 60 * 1000): void {
+    const now = Date.now();
+    for (const [sessionId, session] of this.sessions.entries()) {
+      if (session.status !== 'running' && session.finishedAt) {
+        if (now - session.finishedAt.getTime() > maxAgeMs) {
+          this.sessions.delete(sessionId);
+          logger.debug(`Cleaned up old test session: ${sessionId}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Cancel all running test sessions (for cleanup)
+   */
+  async cancelAll(): Promise<void> {
+    logger.info(`Cancelling all ${this.sessions.size} test sessions`);
+
+    for (const session of this.sessions.values()) {
+      if (session.status === 'running') {
+        await this.stopTests(session.id);
+      }
+    }
+  }
+
+  /**
+   * Cleanup service resources
+   */
+  async cleanup(): Promise<void> {
+    await this.cancelAll();
+    this.sessions.clear();
+  }
+}
+
+// Singleton instance
+let testRunnerServiceInstance: TestRunnerService | null = null;
+
+export function getTestRunnerService(): TestRunnerService {
+  if (!testRunnerServiceInstance) {
+    testRunnerServiceInstance = new TestRunnerService();
+  }
+  return testRunnerServiceInstance;
+}
+
+// Cleanup on process exit
+process.on('SIGTERM', async () => {
+  if (testRunnerServiceInstance) {
+    await testRunnerServiceInstance.cleanup();
+  }
+});
+
+process.on('SIGINT', async () => {
+  if (testRunnerServiceInstance) {
+    await testRunnerServiceInstance.cleanup();
+  }
+});
+
+// Export the class for testing purposes
+export { TestRunnerService };