grimoire-framework 1.0.0

package/.grimoire/core/orchestration/terminal-spawner.js

@@ -0,0 +1,1044 @@
+/**
+ * Terminal Spawner - Node.js wrapper for pm.sh
+ *
+ * Provides async API for spawning grimoire agents in separate terminals
+ * to maintain clean context isolation during orchestration.
+ *
+ * Story 11.2: Bob Terminal Spawning
+ *
+ * @module core/orchestration/terminal-spawner
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { spawn, execSync } = require('child_process');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Constants
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_TIMEOUT_MS = 300000; // 5 minutes
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1000;
+
+/**
+ * Environment types for spawn strategy selection
+ * @readonly
+ * @enum {string}
+ */
+const ENVIRONMENT_TYPE = {
+  NATIVE_TERMINAL: 'NATIVE_TERMINAL',
+  VSCODE: 'VSCODE',
+  SSH: 'SSH',
+  DOCKER: 'DOCKER',
+  CI: 'CI',
+};
+
+/**
+ * Environment detection result
+ * @typedef {Object} EnvironmentInfo
+ * @property {string} type - Environment type (ENVIRONMENT_TYPE enum value)
+ * @property {boolean} supportsVisualTerminal - Whether visual terminal spawn is supported
+ * @property {string} reason - Human-readable reason for detection
+ */
+
+/**
+ * Detects the current execution environment (Story 12.10 - Task 1)
+ *
+ * Detection priority:
+ * 1. CI/CD (GitHub Actions, GitLab CI, etc.)
+ * 2. Docker container
+ * 3. SSH session
+ * 4. VS Code integrated terminal
+ * 5. Native terminal (default)
+ *
+ * @returns {EnvironmentInfo} Environment detection result
+ */
+function detectEnvironment() {
+  // 1. CI/CD detection (Task 1.5)
+  // Check common CI environment variables
+  if (
+    process.env.CI === 'true' ||
+    process.env.GITHUB_ACTIONS === 'true' ||
+    process.env.GITLAB_CI === 'true' ||
+    process.env.JENKINS_URL ||
+    process.env.TRAVIS === 'true' ||
+    process.env.CIRCLECI === 'true' ||
+    process.env.BUILDKITE === 'true' ||
+    process.env.AZURE_PIPELINES === 'true' ||
+    process.env.TF_BUILD === 'True'
+  ) {
+    return {
+      type: ENVIRONMENT_TYPE.CI,
+      supportsVisualTerminal: false,
+      reason: 'CI/CD environment detected (headless)',
+    };
+  }
+
+  // 2. Docker container detection (Task 1.4)
+  // Check for /.dockerenv file or cgroup indicators
+  try {
+    if (fsSync.existsSync('/.dockerenv')) {
+      return {
+        type: ENVIRONMENT_TYPE.DOCKER,
+        supportsVisualTerminal: false,
+        reason: 'Docker container detected (/.dockerenv exists)',
+      };
+    }
+
+    // Check cgroup for docker/containerd/kubepods
+    if (fsSync.existsSync('/proc/1/cgroup')) {
+      const cgroup = fsSync.readFileSync('/proc/1/cgroup', 'utf8');
+      if (cgroup.includes('docker') || cgroup.includes('containerd') || cgroup.includes('kubepods')) {
+        return {
+          type: ENVIRONMENT_TYPE.DOCKER,
+          supportsVisualTerminal: false,
+          reason: 'Container detected via cgroup',
+        };
+      }
+    }
+  } catch {
+    // Ignore file read errors (e.g., on Windows)
+  }
+
+  // 3. SSH session detection (Task 1.3)
+  if (process.env.SSH_CLIENT || process.env.SSH_TTY || process.env.SSH_CONNECTION) {
+    return {
+      type: ENVIRONMENT_TYPE.SSH,
+      supportsVisualTerminal: false,
+      reason: 'SSH session detected (no display available)',
+    };
+  }
+
+  // 4. VS Code integrated terminal detection (Task 1.2)
+  if (
+    process.env.TERM_PROGRAM === 'vscode' ||
+    process.env.VSCODE_PID ||
+    process.env.VSCODE_CWD ||
+    process.env.VSCODE_GIT_IPC_HANDLE
+  ) {
+    return {
+      type: ENVIRONMENT_TYPE.VSCODE,
+      supportsVisualTerminal: false,
+      reason: 'VS Code integrated terminal detected',
+    };
+  }
+
+  // 5. Native terminal (default) - supports visual spawn
+  return {
+    type: ENVIRONMENT_TYPE.NATIVE_TERMINAL,
+    supportsVisualTerminal: true,
+    reason: 'Native terminal environment',
+  };
+}
+
+/**
+ * Default spawn options
+ * @type {Object}
+ */
+const DEFAULT_OPTIONS = {
+  params: '',
+  context: null,
+  timeout: DEFAULT_TIMEOUT_MS,
+  outputDir: os.tmpdir(),
+  retries: MAX_RETRIES,
+  debug: false,
+};
+
+/**
+ * Context schema for agent execution
+ * @typedef {Object} AgentContext
+ * @property {string} story - Story file path or content
+ * @property {string[]} files - Array of relevant file paths
+ * @property {string} instructions - Additional instructions for the agent
+ * @property {Object} metadata - Additional metadata
+ */
+
+/**
+ * Spawn result object
+ * @typedef {Object} SpawnResult
+ * @property {boolean} success - Whether spawn was successful
+ * @property {string} output - Agent output content
+ * @property {string} outputFile - Path to output file
+ * @property {number} duration - Execution duration in ms
+ * @property {string} [error] - Error message if failed
+ */
+
+/**
+ * Gets the path to the pm.sh script
+ * @returns {string} Absolute path to pm.sh
+ */
+function getScriptPath() {
+  return path.join(__dirname, '../../scripts/pm.sh');
+}
+
+/**
+ * Validates spawn arguments
+ * @param {string} agent - Agent ID
+ * @param {string} task - Task to execute
+ * @throws {Error} If arguments are invalid
+ */
+function validateArgs(agent, task) {
+  if (!agent || typeof agent !== 'string') {
+    throw new Error('Agent ID is required and must be a string');
+  }
+
+  if (!task || typeof task !== 'string') {
+    throw new Error('Task is required and must be a string');
+  }
+
+  // Validate agent format (should be alphanumeric with optional hyphen)
+  const agentPattern = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+  if (!agentPattern.test(agent)) {
+    throw new Error(`Invalid agent ID format: ${agent}`);
+  }
+
+  // Validate task format
+  const taskPattern = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+  if (!taskPattern.test(task)) {
+    throw new Error(`Invalid task format: ${task}`);
+  }
+}
+
+/**
+ * Creates a temporary context file for the agent (Task 2.2)
+ *
+ * @param {AgentContext} context - Context data to pass to agent
+ * @param {string} outputDir - Directory for temp files
+ * @returns {Promise<string>} Path to created context file
+ */
+async function createContextFile(context, outputDir = os.tmpdir()) {
+  if (!context) {
+    return '';
+  }
+
+  // Validate context structure
+  const validatedContext = {
+    story: context.story || '',
+    files: Array.isArray(context.files) ? context.files : [],
+    instructions: context.instructions || '',
+    metadata: context.metadata || {},
+    createdAt: new Date().toISOString(),
+  };
+
+  const contextPath = path.join(outputDir, `grimoire-context-${Date.now()}.json`);
+  await fs.writeFile(contextPath, JSON.stringify(validatedContext, null, 2));
+
+  return contextPath;
+}
+
+/**
+ * Polls for agent output completion (Task 3.2, 3.3)
+ *
+ * @param {string} outputFile - Path to output file
+ * @param {number} timeout - Timeout in milliseconds
+ * @param {boolean} debug - Enable debug logging
+ * @returns {Promise<string>} Output content
+ * @throws {Error} If timeout exceeded
+ */
+async function pollForOutput(outputFile, timeout = DEFAULT_TIMEOUT_MS, debug = false) {
+  const startTime = Date.now();
+  const lockFile = outputFile.replace('output', 'lock');
+
+  if (debug) {
+    console.log(`[TerminalSpawner] Polling for output: ${outputFile}`);
+    console.log(`[TerminalSpawner] Lock file: ${lockFile}`);
+  }
+
+  while (Date.now() - startTime < timeout) {
+    // Check if lock file is gone (agent finished)
+    try {
+      await fs.access(lockFile);
+      // Lock still exists, wait and retry
+      if (debug) {
+        console.log(`[TerminalSpawner] Lock exists, waiting ${POLL_INTERVAL_MS}ms...`);
+      }
+      await sleep(POLL_INTERVAL_MS);
+    } catch {
+      // Lock gone, agent finished - read output
+      if (debug) {
+        console.log('[TerminalSpawner] Lock removed, reading output...');
+      }
+
+      try {
+        const output = await fs.readFile(outputFile, 'utf8');
+        return output;
+      } catch (readError) {
+        if (debug) {
+          console.log(`[TerminalSpawner] Output file not found: ${readError.message}`);
+        }
+        return 'No output captured';
+      }
+    }
+  }
+
+  // Timeout - cleanup lock file if still exists
+  try {
+    await fs.unlink(lockFile);
+  } catch {
+    // Ignore cleanup errors
+  }
+
+  throw new Error(`Timeout waiting for agent output after ${timeout}ms`);
+}
+
+/**
+ * Sleep utility
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Spawns an agent inline using child_process.spawn (Story 12.10 - Task 2)
+ *
+ * This is used when visual terminal spawning is not available (VS Code, SSH, Docker, CI).
+ * Output is piped directly instead of using a separate terminal window.
+ *
+ * @param {string} agent - Agent ID (e.g., 'dev', 'architect', 'qa')
+ * @param {string} task - Task to execute
+ * @param {Object} options - Spawn options
+ * @param {string} [options.params=''] - Additional parameters
+ * @param {AgentContext} [options.context=null] - Context data for agent
+ * @param {number} [options.timeout=300000] - Timeout in ms
+ * @param {string} [options.outputDir] - Directory for output files
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {Promise<SpawnResult>} Result with output and status
+ */
+async function spawnInline(agent, task, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const startTime = Date.now();
+
+  if (opts.debug) {
+    console.log('[TerminalSpawner] Using inline spawn (no visual terminal)');
+  }
+
+  // Create context file if needed
+  let contextPath = '';
+  if (opts.context) {
+    contextPath = await createContextFile(opts.context, opts.outputDir);
+    if (opts.debug) {
+      console.log(`[TerminalSpawner] Created context file: ${contextPath}`);
+    }
+  }
+
+  // Build command arguments for pm.sh
+  const args = [agent, task];
+  if (opts.params) {
+    args.push(opts.params);
+  }
+  if (contextPath) {
+    args.push('--context', contextPath);
+  }
+
+  const scriptPath = getScriptPath();
+
+  // Verify script exists
+  if (!fsSync.existsSync(scriptPath)) {
+    throw new Error(`pm.sh script not found at: ${scriptPath}`);
+  }
+
+  return new Promise((resolve) => {
+    const outputChunks = [];
+    const errorChunks = [];
+
+    // Spawn the process inline with piped stdout/stderr (Task 2.2)
+    const child = spawn('bash', [scriptPath, ...args], {
+      env: {
+        ...process.env,
+        grimoire_DEBUG: opts.debug ? 'true' : 'false',
+        grimoire_OUTPUT_DIR: opts.outputDir,
+        grimoire_INLINE_MODE: 'true', // Signal to pm.sh that we're running inline
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    // Register child process for cleanup on parent exit (Task 3.4)
+    registerChildProcess(child);
+
+    // Capture stdout
+    child.stdout.on('data', (data) => {
+      outputChunks.push(data);
+      if (opts.debug) {
+        process.stdout.write(data);
+      }
+    });
+
+    // Capture stderr
+    child.stderr.on('data', (data) => {
+      errorChunks.push(data);
+      if (opts.debug) {
+        process.stderr.write(data);
+      }
+    });
+
+    // Set timeout
+    const timeoutId = setTimeout(() => {
+      child.kill('SIGTERM');
+      const duration = Date.now() - startTime;
+
+      // Cleanup context file
+      if (contextPath) {
+        fs.unlink(contextPath).catch(() => {});
+      }
+
+      resolve({
+        success: false,
+        output: Buffer.concat(outputChunks).toString('utf8'),
+        outputFile: '',
+        duration,
+        error: `Timeout after ${opts.timeout}ms`,
+      });
+    }, opts.timeout);
+
+    // Handle process completion
+    child.on('close', async (code) => {
+      clearTimeout(timeoutId);
+      const duration = Date.now() - startTime;
+
+      // Cleanup context file
+      if (contextPath) {
+        fs.unlink(contextPath).catch(() => {});
+      }
+
+      const stdout = Buffer.concat(outputChunks).toString('utf8').trim();
+      const stderr = Buffer.concat(errorChunks).toString('utf8');
+
+      if (code === 0) {
+        // pm.sh returns the output file path in stdout
+        // Read the actual output from that file
+        let output = stdout;
+        const outputFilePath = stdout.split('\n').pop()?.trim();
+
+        if (outputFilePath && outputFilePath.endsWith('.md')) {
+          try {
+            output = await fs.readFile(outputFilePath, 'utf8');
+            // Cleanup the output file after reading
+            await fs.unlink(outputFilePath).catch(() => {});
+          } catch {
+            // If we can't read the file, use stdout as fallback
+            output = stdout;
+          }
+        }
+
+        resolve({
+          success: true,
+          output,
+          outputFile: outputFilePath || '',
+          duration,
+        });
+      } else {
+        resolve({
+          success: false,
+          output: stdout,
+          outputFile: '',
+          duration,
+          error: stderr || `Process exited with code ${code}`,
+        });
+      }
+    });
+
+    // Handle spawn errors
+    child.on('error', (error) => {
+      clearTimeout(timeoutId);
+      const duration = Date.now() - startTime;
+
+      // Cleanup context file
+      if (contextPath) {
+        fs.unlink(contextPath).catch(() => {});
+      }
+
+      resolve({
+        success: false,
+        output: Buffer.concat(outputChunks).toString('utf8'),
+        outputFile: '',
+        duration,
+        error: error.message,
+      });
+    });
+  });
+}
+
+/**
+ * Spawns an agent in a separate terminal (Task 4.1)
+ *
+ * Opens a new terminal window with the specified agent and task,
+ * passing context if provided. Returns the agent's output after completion.
+ *
+ * @param {string} agent - Agent ID (e.g., 'dev', 'architect', 'qa')
+ * @param {string} task - Task to execute (e.g., 'develop', 'review')
+ * @param {Object} options - Spawn options
+ * @param {string} [options.params=''] - Additional parameters
+ * @param {AgentContext} [options.context=null] - Context data for agent
+ * @param {number} [options.timeout=300000] - Timeout in ms (default: 5 min)
+ * @param {string} [options.outputDir] - Directory for output files
+ * @param {number} [options.retries=3] - Number of retry attempts
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {Promise<SpawnResult>} Result with output and status
+ *
+ * @example
+ * const result = await spawnAgent('dev', 'develop', {
+ *   params: 'story-11.2',
+ *   context: {
+ *     story: 'docs/stories/active/11.2.story.md',
+ *     files: ['src/index.js'],
+ *     instructions: 'Focus on terminal spawning'
+ *   },
+ *   timeout: 600000 // 10 minutes
+ * });
+ */
+async function spawnAgent(agent, task, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const startTime = Date.now();
+
+  // Validate arguments
+  validateArgs(agent, task);
+
+  // Detect environment to determine spawn strategy (Story 12.10 - Task 2.5)
+  const environment = detectEnvironment();
+
+  if (opts.debug) {
+    console.log(`[TerminalSpawner] Environment: ${environment.type} (${environment.reason})`);
+  }
+
+  // If environment doesn't support visual terminal, use inline spawn directly
+  if (!environment.supportsVisualTerminal) {
+    console.log(`⚠️ Terminal visual indisponível. Executando inline. [${environment.reason}]`);
+    return spawnInline(agent, task, opts);
+  }
+
+  // Create context file if needed (Task 2.2)
+  let contextPath = '';
+  if (opts.context) {
+    contextPath = await createContextFile(opts.context, opts.outputDir);
+    if (opts.debug) {
+      console.log(`[TerminalSpawner] Created context file: ${contextPath}`);
+    }
+  }
+
+  // Build command arguments
+  const args = [agent, task];
+  if (opts.params) {
+    args.push(opts.params);
+  }
+  if (contextPath) {
+    args.push('--context', contextPath);
+  }
+
+  // Get script path
+  const scriptPath = getScriptPath();
+
+  // Verify script exists
+  if (!fsSync.existsSync(scriptPath)) {
+    throw new Error(`pm.sh script not found at: ${scriptPath}`);
+  }
+
+  // Execute with retry logic (Task 4.2)
+  let lastError;
+  for (let attempt = 1; attempt <= opts.retries; attempt++) {
+    try {
+      if (opts.debug) {
+        console.log(`[TerminalSpawner] Attempt ${attempt}/${opts.retries}`);
+        console.log(`[TerminalSpawner] Executing: bash ${scriptPath} ${args.join(' ')}`);
+      }
+
+      // Execute pm.sh
+      const env = {
+        ...process.env,
+        grimoire_DEBUG: opts.debug ? 'true' : 'false',
+        grimoire_OUTPUT_DIR: opts.outputDir,
+      };
+
+      const result = execSync(`bash "${scriptPath}" ${args.join(' ')}`, {
+        encoding: 'utf8',
+        timeout: opts.timeout,
+        env,
+      });
+
+      // Get output file path from script output
+      const outputFile = result.trim();
+
+      if (opts.debug) {
+        console.log(`[TerminalSpawner] Output file: ${outputFile}`);
+      }
+
+      // Poll for completion (Task 3.2, 3.3)
+      const output = await pollForOutput(outputFile, opts.timeout, opts.debug);
+
+      // Cleanup context file (Task 2.4)
+      if (contextPath) {
+        await fs.unlink(contextPath).catch(() => {});
+      }
+
+      const duration = Date.now() - startTime;
+
+      return {
+        success: true,
+        output,
+        outputFile,
+        duration,
+      };
+    } catch (error) {
+      lastError = error;
+      if (opts.debug) {
+        console.log(`[TerminalSpawner] Attempt ${attempt} failed: ${error.message}`);
+      }
+
+      if (attempt < opts.retries) {
+        await sleep(RETRY_DELAY_MS * attempt);
+      }
+    }
+  }
+
+  // Fallback to inline spawn if visual terminal fails (Story 12.10 - Task 2.3)
+  console.log('⚠️ Terminal visual falhou. Tentando execução inline como fallback...');
+
+  // Cleanup context file before retry with inline
+  if (contextPath) {
+    await fs.unlink(contextPath).catch(() => {});
+  }
+
+  // Try inline spawn as fallback
+  const inlineResult = await spawnInline(agent, task, opts);
+
+  if (inlineResult.success) {
+    console.log('✅ Execução inline bem-sucedida.');
+    return inlineResult;
+  }
+
+  // Both methods failed
+  const duration = Date.now() - startTime;
+
+  return {
+    success: false,
+    output: inlineResult.output || '',
+    outputFile: '',
+    duration,
+    error: `Visual spawn failed: ${lastError?.message || 'Unknown'}. Inline fallback also failed: ${inlineResult.error || 'Unknown'}`,
+  };
+}
+
+/**
+ * Checks if the terminal spawner is available on this platform
+ * @returns {boolean} True if spawning is supported
+ */
+function isSpawnerAvailable() {
+  const platform = process.platform;
+  return ['darwin', 'linux', 'win32'].includes(platform);
+}
+
+/**
+ * Gets the current platform name
+ * @returns {string} Platform name (macos, linux, windows, or unknown)
+ */
+function getPlatform() {
+  switch (process.platform) {
+    case 'darwin':
+      return 'macos';
+    case 'linux':
+      return 'linux';
+    case 'win32':
+      return 'windows';
+    default:
+      return 'unknown';
+  }
+}
+
+/**
+ * Cleans up old output and lock files (Task 2.4)
+ *
+ * @param {string} outputDir - Directory to clean
+ * @param {number} maxAgeMs - Maximum age in milliseconds (default: 1 hour)
+ * @returns {Promise<number>} Number of files cleaned
+ */
+async function cleanupOldFiles(outputDir = os.tmpdir(), maxAgeMs = 3600000) {
+  const now = Date.now();
+  let cleaned = 0;
+
+  try {
+    const files = await fs.readdir(outputDir);
+    const grimoireFiles = files.filter(
+      (f) => f.startsWith('grimoire-output-') || f.startsWith('grimoire-lock-') || f.startsWith('grimoire-context-'),
+    );
+
+    for (const file of grimoireFiles) {
+      const filePath = path.join(outputDir, file);
+      try {
+        const stats = await fs.stat(filePath);
+        if (now - stats.mtimeMs > maxAgeMs) {
+          await fs.unlink(filePath);
+          cleaned++;
+        }
+      } catch {
+        // Ignore errors for individual files
+      }
+    }
+  } catch {
+    // Ignore directory read errors
+  }
+
+  return cleaned;
+}
+
+// ============================================
+// OS Compatibility Matrix (Story 12.10 - Task 7)
+// ============================================
+
+/**
+ * OS Compatibility Matrix definition (PRD §9.6 — D19)
+ * @type {Object}
+ */
+const OS_COMPATIBILITY_MATRIX = {
+  must_pass: [
+    { os: 'macOS Sonoma', arch: 'arm64', docker: 'Docker Desktop', description: 'Apple Silicon' },
+    { os: 'macOS Sonoma', arch: 'x64', docker: 'Docker Desktop', description: 'Intel' },
+    { os: 'Windows 11', arch: 'x64', docker: 'Docker Desktop', wsl: 'Ubuntu 22.04', description: 'WSL2' },
+    { os: 'Ubuntu 22.04', arch: 'x64', docker: 'Docker Engine', description: 'Native Linux' },
+  ],
+  should_pass: [
+    { os: 'Windows 10', arch: 'x64', wsl: 'Ubuntu', description: 'WSL2' },
+    { os: 'macOS Ventura', arch: 'arm64', docker: 'Docker Desktop', description: 'Previous macOS' },
+    { os: 'macOS Ventura', arch: 'x64', docker: 'Docker Desktop', description: 'Previous macOS Intel' },
+    { os: 'Ubuntu 24.04', arch: 'x64', docker: 'Docker Engine', description: 'Latest Ubuntu' },
+  ],
+};
+
+/**
+ * Compatibility test result
+ * @typedef {Object} CompatibilityTestResult
+ * @property {string} testName - Name of the test
+ * @property {string} result - 'pass' | 'fail' | 'skip'
+ * @property {string} [failureReason] - Reason for failure if applicable
+ * @property {number} duration - Test duration in ms
+ */
+
+/**
+ * Compatibility report structure
+ * @typedef {Object} CompatibilityReport
+ * @property {string} generatedAt - ISO timestamp
+ * @property {Object} system - System information
+ * @property {string} system.os_name - Operating system name
+ * @property {string} system.os_version - OS version
+ * @property {string} system.architecture - CPU architecture (x64, arm64)
+ * @property {string} system.shell - Default shell
+ * @property {string} system.docker_version - Docker version or 'not installed'
+ * @property {string} system.node_version - Node.js version
+ * @property {Object} environment - Detected environment
+ * @property {CompatibilityTestResult[]} tests - Test results
+ * @property {Object} summary - Summary statistics
+ */
+
+/**
+ * Gets current system information for compatibility reporting (Task 7.4)
+ * @returns {Object} System information
+ */
+function getSystemInfo() {
+  const { execSync } = require('child_process');
+
+  // Get OS info
+  const platform = os.platform();
+  const release = os.release();
+  const arch = os.arch();
+
+  // Get OS name
+  let osName = 'Unknown';
+  if (platform === 'darwin') {
+    try {
+      const swVers = execSync('sw_vers -productName 2>/dev/null', { encoding: 'utf8' }).trim();
+      const swVersion = execSync('sw_vers -productVersion 2>/dev/null', { encoding: 'utf8' }).trim();
+      osName = `${swVers} ${swVersion}`;
+    } catch {
+      osName = `macOS ${release}`;
+    }
+  } else if (platform === 'linux') {
+    try {
+      const lsbRelease = execSync('lsb_release -d 2>/dev/null || cat /etc/os-release 2>/dev/null | grep PRETTY_NAME | cut -d= -f2 | tr -d \'"\'', { encoding: 'utf8' }).trim();
+      osName = lsbRelease.replace('Description:\t', '') || `Linux ${release}`;
+    } catch {
+      osName = `Linux ${release}`;
+    }
+  } else if (platform === 'win32') {
+    osName = `Windows ${release}`;
+  }
+
+  // Get shell
+  const shell = process.env.SHELL || process.env.ComSpec || 'unknown';
+
+  // Get Docker version
+  let dockerVersion = 'not installed';
+  try {
+    dockerVersion = execSync('docker --version 2>/dev/null', { encoding: 'utf8' }).trim();
+  } catch {
+    // Docker not available
+  }
+
+  // Get Node version
+  const nodeVersion = process.version;
+
+  return {
+    os_name: osName,
+    os_version: release,
+    architecture: arch,
+    shell: path.basename(shell),
+    docker_version: dockerVersion,
+    node_version: nodeVersion,
+  };
+}
+
+/**
+ * Generates a compatibility report after test run (Task 7.4, 7.5)
+ *
+ * @param {CompatibilityTestResult[]} testResults - Array of test results
+ * @returns {CompatibilityReport} Generated compatibility report
+ */
+function generateCompatibilityReport(testResults = []) {
+  const systemInfo = getSystemInfo();
+  const environment = detectEnvironment();
+
+  // Calculate summary
+  const passed = testResults.filter((t) => t.result === 'pass').length;
+  const failed = testResults.filter((t) => t.result === 'fail').length;
+  const skipped = testResults.filter((t) => t.result === 'skip').length;
+  const total = testResults.length;
+
+  // Determine matrix classification
+  const matchesMustPass = OS_COMPATIBILITY_MATRIX.must_pass.some(
+    (m) => systemInfo.os_name.toLowerCase().includes(m.os.toLowerCase().split(' ')[0]),
+  );
+  const matchesShouldPass = OS_COMPATIBILITY_MATRIX.should_pass.some(
+    (m) => systemInfo.os_name.toLowerCase().includes(m.os.toLowerCase().split(' ')[0]),
+  );
+
+  return {
+    generatedAt: new Date().toISOString(),
+    system: systemInfo,
+    environment: {
+      type: environment.type,
+      supportsVisualTerminal: environment.supportsVisualTerminal,
+      reason: environment.reason,
+    },
+    matrixClassification: matchesMustPass ? 'must_pass' : matchesShouldPass ? 'should_pass' : 'not_in_matrix',
+    tests: testResults,
+    summary: {
+      total,
+      passed,
+      failed,
+      skipped,
+      passRate: total > 0 ? Math.round((passed / total) * 100) : 0,
+    },
+  };
+}
+
+/**
+ * Formats compatibility report for console output (Task 7.5)
+ * @param {CompatibilityReport} report - Compatibility report
+ * @returns {string} Formatted report string
+ */
+function formatCompatibilityReport(report) {
+  const lines = [
+    '═══════════════════════════════════════════════════════════════',
+    '                 grimoire Terminal Spawner Compatibility Report     ',
+    '═══════════════════════════════════════════════════════════════',
+    '',
+    `Generated: ${report.generatedAt}`,
+    '',
+    '── System Information ──────────────────────────────────────────',
+    `  OS:           ${report.system.os_name}`,
+    `  Version:      ${report.system.os_version}`,
+    `  Architecture: ${report.system.architecture}`,
+    `  Shell:        ${report.system.shell}`,
+    `  Docker:       ${report.system.docker_version}`,
+    `  Node.js:      ${report.system.node_version}`,
+    '',
+    '── Environment Detection ───────────────────────────────────────',
+    `  Type:         ${report.environment.type}`,
+    `  Visual Term:  ${report.environment.supportsVisualTerminal ? 'Yes' : 'No'}`,
+    `  Reason:       ${report.environment.reason}`,
+    '',
+    `  Matrix Class: ${report.matrixClassification.toUpperCase()}`,
+    '',
+  ];
+
+  if (report.tests.length > 0) {
+    lines.push('── Test Results ────────────────────────────────────────────────');
+    for (const test of report.tests) {
+      const icon = test.result === 'pass' ? '✅' : test.result === 'fail' ? '❌' : '⏭️';
+      const duration = test.duration ? ` (${test.duration}ms)` : '';
+      lines.push(`  ${icon} ${test.testName}${duration}`);
+      if (test.failureReason) {
+        lines.push(`     └─ ${test.failureReason}`);
+      }
+    }
+    lines.push('');
+  }
+
+  lines.push('── Summary ─────────────────────────────────────────────────────');
+  lines.push(`  Total:   ${report.summary.total}`);
+  lines.push(`  Passed:  ${report.summary.passed}`);
+  lines.push(`  Failed:  ${report.summary.failed}`);
+  lines.push(`  Skipped: ${report.summary.skipped}`);
+  lines.push(`  Rate:    ${report.summary.passRate}%`);
+  lines.push('');
+  lines.push('═══════════════════════════════════════════════════════════════');
+
+  return lines.join('\n');
+}
+
+// ============================================
+// Lock File Cleanup and Signal Handling (Story 12.10 - Task 3)
+// ============================================
+
+/**
+ * Active lock files being tracked for cleanup
+ * @type {Set<string>}
+ */
+const activeLockFiles = new Set();
+
+/**
+ * Active child processes being tracked for cleanup
+ * @type {Set<ChildProcess>}
+ */
+const activeChildProcesses = new Set();
+
+/**
+ * Registers a lock file for cleanup on process exit
+ * @param {string} lockPath - Path to lock file
+ */
+function registerLockFile(lockPath) {
+  activeLockFiles.add(lockPath);
+}
+
+/**
+ * Unregisters a lock file (called when process completes normally)
+ * @param {string} lockPath - Path to lock file
+ */
+function unregisterLockFile(lockPath) {
+  activeLockFiles.delete(lockPath);
+}
+
+/**
+ * Registers a child process for cleanup on parent exit
+ * @param {ChildProcess} child - Child process to track
+ */
+function registerChildProcess(child) {
+  activeChildProcesses.add(child);
+  child.on('close', () => {
+    activeChildProcesses.delete(child);
+  });
+}
+
+/**
+ * Cleans up all registered lock files (Task 3.3)
+ * Called on process exit or signal
+ */
+function cleanupLocks() {
+  for (const lockPath of activeLockFiles) {
+    try {
+      if (fsSync.existsSync(lockPath)) {
+        fsSync.unlinkSync(lockPath);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+  activeLockFiles.clear();
+}
+
+/**
+ * Terminates all active child processes (Task 3.4)
+ */
+function terminateChildProcesses() {
+  for (const child of activeChildProcesses) {
+    try {
+      child.kill('SIGTERM');
+    } catch {
+      // Ignore if already dead
+    }
+  }
+  activeChildProcesses.clear();
+}
+
+/**
+ * Cleanup handler for process exit/signals (Task 3.4)
+ * @param {string} signal - Signal name or 'exit'
+ */
+function cleanupHandler(signal) {
+  console.log(`[TerminalSpawner] Cleanup triggered by ${signal}`);
+  cleanupLocks();
+  terminateChildProcesses();
+}
+
+// Register cleanup handlers (Task 3.4)
+// Only register once, even if module is required multiple times
+if (!process._terminalSpawnerCleanupRegistered) {
+  process._terminalSpawnerCleanupRegistered = true;
+
+  // Normal exit
+  process.on('exit', () => cleanupHandler('exit'));
+
+  // Ctrl+C
+  process.on('SIGINT', () => {
+    cleanupHandler('SIGINT');
+    process.exit(1);
+  });
+
+  // Termination signal (kill command)
+  process.on('SIGTERM', () => {
+    cleanupHandler('SIGTERM');
+    process.exit(1);
+  });
+
+  // Uncaught exception (try to cleanup before crash)
+  process.on('uncaughtException', (error) => {
+    console.error('[TerminalSpawner] Uncaught exception:', error);
+    cleanupHandler('uncaughtException');
+    process.exit(1);
+  });
+
+  // Unhandled promise rejection
+  process.on('unhandledRejection', (reason) => {
+    console.error('[TerminalSpawner] Unhandled rejection:', reason);
+    cleanupHandler('unhandledRejection');
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  // Main API
+  spawnAgent,
+  spawnInline,
+  createContextFile,
+  pollForOutput,
+
+  // Environment Detection (Story 12.10)
+  detectEnvironment,
+  ENVIRONMENT_TYPE,
+
+  // OS Compatibility Matrix (Story 12.10 - Task 7)
+  OS_COMPATIBILITY_MATRIX,
+  getSystemInfo,
+  generateCompatibilityReport,
+  formatCompatibilityReport,
+
+  // Utilities
+  isSpawnerAvailable,
+  getPlatform,
+  cleanupOldFiles,
+  getScriptPath,
+
+  // Lock Management (Story 12.10)
+  registerLockFile,
+  unregisterLockFile,
+  cleanupLocks,
+
+  // Constants
+  DEFAULT_TIMEOUT_MS,
+  POLL_INTERVAL_MS,
+  MAX_RETRIES,
+};
+