@ts47andres/exeggutor 1.1.4 → 1.1.5

package/packages/backend/src/ptyManager.ts

@@ -1,414 +1,414 @@
-import * as pty from 'node-pty';
-import * as os from 'os';
-import * as path from 'path';
-import * as fs from 'fs';
-import { exec } from 'child_process';
-import * as db from './workspaceDb'; // Reference to local sessions JSON database.
-
-export interface TerminalSession {
-  id: string; // The unique tab ID associated with this terminal process.
-  workspaceId: string; // The ID of the workspace that owns this session.
-  ptyProcess: pty.IPty; // The live node-pty process instance.
-  outputBuffer: string[]; // Accumulated recent terminal output lines.
-  lastOutputTime: number; // Unix timestamp of the last stdout chunk received.
-  status: 'Active' | 'Waiting' | 'Idle' | 'Errored'; // Real-time state of the terminal process.
-  lastLinePreview: string; // The single most recent line of terminal output for sidebar observers.
-  onData: (data: string) => void; // Event dispatcher callback for new stdout streams.
-  activeSocket?: any; // The active WebSocket connection associated with this session.
-  broadcastCallback?: () => void; // Optional callback to notify observer of state changes.
-}
-
-const sessions = new Map<string, TerminalSession>(); // Global map cache linking tab IDs to their active persistent TerminalSessions.
-let statusCheckInterval: NodeJS.Timeout | null = null; // Background interval reference for running periodic status audits.
-let spawnLock: Promise<void> | null = null; // Mutex promise ensuring only one PTY spawn executes at a time on Windows.
-let killLock: Promise<void> | null = null; // Mutex promise ensuring only one PTY kill executes at a time on Windows.
-
-// Queries the operating system to recursively find all active child and descendant process IDs of the specified parent process.
-function getDescendants(parentPid: number): Promise<Array<{ pid: number; name: string }>> {
-  console.log(`[PTY] getDescendants(parentPid=${parentPid})`);
-  const p = new Promise<Array<{ pid: number; name: string }>>((resolve) => {
-    const isWin = process.platform === 'win32'; // Flag denoting if the host operating system is Windows.
-    const cmd = isWin ? 'wmic process get ParentProcessId,ProcessId,Name' : 'ps -A -o ppid,pid,comm'; // System command to run.
-    console.log(`[PTY] getDescendants -> running: "${cmd}"`);
-    const runOptions = { windowsHide: true }; // Hide window option.
-    exec(cmd, runOptions, (err, stdout) => {
-      if (err || !stdout) {
-        resolve([]);
-        return;
-      }
-      const lines = stdout.split(/\r?\n/); // Process lines array.
-      const procList: Array<{ pid: number; ppid: number; name: string }> = []; // Registry of all active system processes.
-      for (const line of lines) {
-        const parts = line.trim().split(/\s+/); // Splitted columns.
-        if (parts.length >= 3) {
-          if (isWin) {
-            const ppid = parseInt(parts[0], 10); // Parent process identifier.
-            const pid = parseInt(parts[1], 10); // Target process identifier.
-            const name = parts.slice(2).join(' '); // Process executable name.
-            if (!isNaN(pid) && !isNaN(ppid)) {
-              procList.push({ pid, ppid, name });
-            }
-          } else {
-            const ppid = parseInt(parts[0], 10); // Parent process identifier.
-            const pid = parseInt(parts[1], 10); // Target process identifier.
-            const name = parts.slice(2).join(' '); // Executable name or command line.
-            if (!isNaN(pid) && !isNaN(ppid)) {
-              procList.push({ pid, ppid, name });
-            }
-          }
-        }
-      }
-
-      const descendants: Array<{ pid: number; name: string }> = []; // Flat registry of descendant processes.
-      const queue = [parentPid]; // Queue container for breath-first traversal.
-      const visited = new Set<number>(); // Visited PID tracker to prevent circular reference locks.
-      while (queue.length > 0) {
-        const current = queue.shift()!; // Dequeued parent PID.
-        if (visited.has(current)) {
-          continue;
-        }
-        visited.add(current);
-        const children = procList.filter(p => p.ppid === current); // Direct children matching current process.
-        for (const child of children) {
-          descendants.push({ pid: child.pid, name: child.name });
-          queue.push(child.pid);
-        }
-      }
-      console.log(`[PTY] getDescendants(${parentPid}) -> ${descendants.length} descendants: [${descendants.map(d => `${d.name}(${d.pid})`).join(', ')}]`);
-      resolve(descendants);
-    });
-  }); // Spawns execution promise handle.
-  return p;
-}
-
-// Audits the activity state of all terminal sessions to update active vs idle/waiting states.
-export function startStatusAuditor(broadcastCallback: () => void): void {
-  if (statusCheckInterval) {
-    return;
-  }
-  statusCheckInterval = setInterval(async () => {
-    const now = Date.now(); // The current high resolution timestamp.
-    let changed = false; // Flag to indicate if any session state changed during this audit cycle.
-    
-    const sessionPromises = Array.from(sessions.values()).map(async (session) => {
-      const descendants = await getDescendants(session.ptyProcess.pid); // Retrieved process descendants of the PTY.
-      const utilityNames = new Set([
-        'winpty-agent.exe', 'conhost.exe', 'powershell.exe', 'cmd.exe',
-        'wmic.exe', 'openconsole.exe', 'conconsole.exe', 'bash', 'zsh', 'sh', 'ps'
-      ]); // Process utility names set.
-      
-      const hasActiveProcess = descendants.some(d => {
-        const nameLower = d.name.toLowerCase(); // Lowercased process name.
-        const isUtility = Array.from(utilityNames).some(u => nameLower.includes(u.toLowerCase())); // Flag identifying utility processes.
-        return !isUtility;
-      }); // Verification flag identifying if any non-utility process is running.
-
-      if (!hasActiveProcess) {
-        if (session.status !== 'Idle') {
-          session.status = 'Idle';
-          changed = true;
-        }
-      } else {
-        if (session.status === 'Active' && now - session.lastOutputTime > 2000) {
-          const fullOutput = session.outputBuffer.join(''); // Combined stdout stream of the session.
-          const lines = fullOutput.split(/\r?\n/); // Splitted chunk array.
-          const nonLines = lines.map(l => l.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '').trim()); // Cleaned line array without ANSI.
-          const nonZeroLines = nonLines.filter(l => l.length > 0); // Non-empty cleaned lines.
-          const lastFewLines = nonZeroLines.slice(-5); // Last 5 non-empty output lines.
-          const lastFewTextLower = lastFewLines.join(' ').toLowerCase(); // Combined lowercased string of recent lines.
-          const interactiveGuides = ['tab', 'select', 'enter', 'confirm', 'dismiss', 'arrow', 'esc', 'up/down', '[y/n]']; // Interactive keyboard control terms.
-          const promptIndicators = ['password:', 'password for', 'enter passphrase', 'input:', 'confirm:', 'proceed?']; // Standard CLI input indicators.
-          const hasInteractiveGuides = interactiveGuides.some(guide => lastFewTextLower.includes(guide)); // Flag identifying key guides in output.
-          const hasPromptIndicators = promptIndicators.some(indicator => lastFewTextLower.includes(indicator)); // Flag identifying standard prompts in output.
-          const lastLine = nonZeroLines[nonZeroLines.length - 1] || ''; // The single last line of output.
-          const endsWithQuestion = lastLine.endsWith('?') || lastFewLines.some(l => l.endsWith('?')); // Flag verifying if any recent lines end with a question mark.
-          const isWaiting = hasInteractiveGuides || hasPromptIndicators || endsWithQuestion; // Combined check for form prompt or question.
-          const nextStatus = isWaiting ? 'Waiting' : 'Idle'; // Computed target status mapping.
-          session.status = nextStatus;
-          changed = true;
-        }
-      }
-    }); // Spawns concurrent auditing sessions.
-
-    await Promise.all(sessionPromises);
-    if (changed) {
-      broadcastCallback();
-    }
-  }, 5000); // Trigger auditor check every 5 seconds to reduce wmic process spawn frequency on Windows.
-}
-
-// Spawns a persistent terminal process or retrieves an existing one, matching it to the tab.
-// Uses an async spawn lock to serialize concurrent node-pty process creation on Windows.
-export async function getOrCreatePtySession(
-  workspaceId: string,
-  tabId: string,
-  cwd: string,
-  shellPath?: string,
-  broadcastCallback?: () => void
-): Promise<TerminalSession> {
-  const existing = sessions.get(tabId); // Attempt to retrieve an existing session from the cache.
-  if (existing) {
-    console.log(`[PTY] getOrCreatePtySession -> returning existing session for tab=${tabId} PID=${existing.ptyProcess.pid}`);
-    const foundSession = existing; // Explicit reference to the cached session.
-    return foundSession;
-  }
-
-  console.log(`[PTY] getOrCreatePtySession(workspaceId=${workspaceId}, tabId=${tabId}, cwd=${cwd}, shellPath=${shellPath})`);
-
-  const defaultShell = os.platform() === 'win32' ? 'powershell.exe' : 'bash'; // Choose shell path depending on underlying server OS.
-  const targetShell = shellPath || defaultShell; // Evaluated shell executable to run.
-
-  const ptyArgs: string[] = []; // Arguments passed to the spawned shell.
-  const ptyEnv = { ...process.env } as Record<string, string>; // Environment variables for the spawned process.
-
-  const isWin = os.platform() === 'win32'; // Flag indicating Windows platform.
-  if (isWin) {
-    const guardScript = path.resolve(__dirname, '../scripts/git-guard.ps1');
-    if (fs.existsSync(guardScript)) {
-      ptyArgs.push('-NoLogo', '-NoExit', '-ExecutionPolicy', 'Bypass', '-Command', `. '${guardScript}'`);
-    }
-  } else {
-    const wrapperDir = path.resolve(__dirname, '../git-wrapper');
-    if (fs.existsSync(path.join(wrapperDir, 'git'))) {
-      ptyEnv.PATH = `${wrapperDir}${path.delimiter}${ptyEnv.PATH || ''}`;
-    }
-  }
-
-  // Wait for any in-flight PTY spawn to finish before creating a new one to avoid ConPTY conflicts on Windows.
-  while (spawnLock) {
-    console.log(`[PTY] Spawn lock held, waiting for tab=${tabId}`);
-    await spawnLock;
-  }
-  let releaseLock: () => void = () => {}; // Callback to release the spawn mutex after creation completes, default no-op to avoid TS usage-before-init.
-  spawnLock = new Promise((resolve) => { releaseLock = resolve; });
-
-  console.log(`[PTY] Spawning shell: targetShell="${targetShell}" args=[${ptyArgs.join(', ')}] useConpty=true`);
-  let ptyProcess: pty.IPty; // Reference to the successfully spawned node-pty process.
-  try {
-    ptyProcess = pty.spawn(targetShell, ptyArgs, {
-      name: 'xterm-256color',
-      cols: 80,
-      rows: 24,
-      cwd: cwd,
-      env: ptyEnv,
-      useConpty: true, // Enables the Windows Pseudo Console API for accurate dimension resizes.
-    }); // Spawn the process via node-pty.
-    console.log(`[PTY] Spawned PID=${ptyProcess.pid} for tab=${tabId}`);
-  } catch (err: any) {
-    console.log(`[PTY] Spawn FAILED for tab=${tabId}: ${err.message}. Stack: ${err.stack}`);
-    const spawnErr = new Error(`PTY spawn failed for tab ${tabId}: ${err.message}`); // Error wrapping the spawn failure.
-    spawnLock = null;
-    releaseLock();
-    throw spawnErr;
-  }
-  spawnLock = null;
-  releaseLock();
-
-  const newSession: TerminalSession = {
-    id: tabId,
-    workspaceId: workspaceId,
-    ptyProcess: ptyProcess,
-    outputBuffer: [],
-    lastOutputTime: Date.now(),
-    status: 'Idle',
-    lastLinePreview: '',
-    onData: () => {},
-    broadcastCallback: broadcastCallback,
-  }; // The new terminal session schema instance mapping this tab.
-
-  sessions.set(tabId, newSession);
-
-  // Save process PID to database for future orphan recovery.
-  try {
-    db.updateTerminalTab(workspaceId, tabId, { pid: ptyProcess.pid });
-  } catch (err) {
-    // Safe ignore database update failure.
-  }
-
-  ptyProcess.onData(data => {
-    newSession.lastOutputTime = Date.now();
-    
-    const maxBufferLines = 1000; // Limit total cached rows in memory to save memory usage.
-    newSession.outputBuffer.push(data);
-    if (newSession.outputBuffer.length > maxBufferLines) {
-      newSession.outputBuffer.shift();
-    }
-
-    const lines = data.split(/\r?\n/); // Splitted chunk array.
-    const lastNonEmpty = lines.filter(l => l.trim().length > 0).pop(); // The last non-empty line of text.
-    if (lastNonEmpty) {
-      const cleanLine = lastNonEmpty.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '').trim(); // Remove ANSI terminal escape codes.
-      if (cleanLine.length > 0) {
-        newSession.lastLinePreview = cleanLine.substring(0, 100);
-      }
-    }
-
-    const oldStatus = newSession.status; // Preserve original status before computation.
-    newSession.status = 'Active'; // Mark status as active immediately when receiving new data.
-
-    newSession.onData(data);
-
-    if (oldStatus !== newSession.status && broadcastCallback) {
-      broadcastCallback();
-    }
-  });
-
-  ptyProcess.onExit(res => {
-    newSession.status = res.exitCode === 0 ? 'Idle' : 'Errored';
-    if (broadcastCallback) {
-      broadcastCallback();
-    }
-  });
-
-  const createdSession = newSession; // Explicit reference to return.
-  return createdSession;
-}
-
-// Resizes the terminal process row and column dimensions.
-export function resizePtySession(tabId: string, cols: number, rows: number): void {
-  const session = sessions.get(tabId); // Look up session by ID.
-  if (session && typeof cols === 'number' && typeof rows === 'number' && cols > 0 && rows > 0) {
-    const parsedCols = Math.max(Math.floor(cols), 40); // Ensures PTY size is at least 40 columns wide.
-    const parsedRows = Math.max(Math.floor(rows), 10); // Ensures PTY size is at least 10 rows high.
-    if (parsedCols > 0 && parsedRows > 0) {
-      session.ptyProcess.resize(parsedCols, parsedRows);
-    }
-  }
-}
-
-// Write input data directly to the active terminal process.
-// Does not change the session status — the periodic auditor handles status transitions,
-// preventing rapid Idle↔Active flickering that occurred on every keystroke.
-export function writeToPtySession(tabId: string, data: string): void {
-  const session = sessions.get(tabId); // Look up session by ID.
-  if (session) {
-    session.ptyProcess.write(data);
-  }
-}
-
-// Forces the termination of a terminal session and frees system process resources.
-// Serializes concurrent kills on Windows to avoid overlapping conhost termination window flashes.
-export async function killPtySession(tabId: string): Promise<void> {
-  const session = sessions.get(tabId); // Find session by tab ID.
-  if (session) {
-    console.log(`[PTY] killPtySession(tabId=${tabId}) -> killing PID=${session.ptyProcess.pid}`);
-    // Wait for any in-flight PTY kill to finish before terminating this one to avoid ConPTY conflicts on Windows.
-    while (killLock) {
-      console.log(`[PTY] Kill lock held, waiting for tab=${tabId}`);
-      await killLock;
-    }
-    let releaseKillLock: () => void = () => {}; // Callback to release the kill mutex after termination completes.
-    killLock = new Promise((resolve) => { releaseKillLock = resolve; });
-
-    try {
-      session.ptyProcess.kill();
-      console.log(`[PTY] killPtySession(tabId=${tabId}) -> kill OK`);
-    } catch (err: any) {
-      console.log(`[PTY] killPtySession(tabId=${tabId}) -> kill error: ${err.message}`);
-    } finally {
-      killLock = null;
-      releaseKillLock();
-    }
-    try {
-      db.updateTerminalTab(session.workspaceId, tabId, { pid: undefined }); // Clear the PID record from the database.
-    } catch (err) {
-      // Safe ignore database write failure.
-    }
-    sessions.delete(tabId);
-    console.log(`[PTY] killPtySession(tabId=${tabId}) -> session removed from map`);
-  } else {
-    console.log(`[PTY] killPtySession(tabId=${tabId}) -> no active session found`);
-  }
-}
-
-// Retrieves all terminal session descriptors currently managed by the backend.
-export function getAllSessions(): Array<{ id: string; workspaceId: string; status: string; preview: string }> {
-  const list: Array<{ id: string; workspaceId: string; status: string; preview: string }> = []; // Return sessions descriptors.
-  sessions.forEach(s => {
-    list.push({
-      id: s.id,
-      workspaceId: s.workspaceId,
-      status: s.status,
-      preview: s.lastLinePreview,
-    });
-  });
-  return list;
-}
-
-// Verifies that a given PID belongs to an expected Exeggutor-managed process to avoid killing unrelated recycled PIDs.
-function verifyPidOwnership(pid: number): Promise<boolean> {
-  console.log(`[PTY] verifyPidOwnership(pid=${pid})`);
-  return new Promise((resolve) => {
-    const isWin = process.platform === 'win32'; // Flag indicating Windows platform.
-    if (isWin) {
-      console.log(`[PTY] verifyPidOwnership -> running: tasklist /FI "PID eq ${pid}"`);
-      exec(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { windowsHide: true }, (err, stdout) => {
-        if (err || !stdout) {
-          resolve(false);
-          return;
-        }
-        const nameMatch = stdout.match(/"([^"]+)"/); // Capture the process executable name from CSV output.
-        if (!nameMatch) {
-          resolve(false);
-          return;
-        }
-        const name = nameMatch[1].toLowerCase(); // Process name from tasklist.
-        const knownNames = ['node.exe', 'powershell.exe', 'cmd.exe', 'bash.exe', 'wmic.exe', 'conhost.exe'];
-        const result = knownNames.some(k => name.includes(k));
-        console.log(`[PTY] verifyPidOwnership(${pid}) -> process="${name}" known=${result}`);
-        resolve(result);
-      }); // Spawn tasklist to verify process identity.
-    } else {
-      try {
-        const comm = fs.readFileSync(`/proc/${pid}/comm`, 'utf8').trim(); // Process command name from proc filesystem.
-        const knownNames = ['node', 'bash', 'zsh', 'sh', 'dash', 'powershell'];
-        const result = knownNames.includes(comm);
-        console.log(`[PTY] verifyPidOwnership(${pid}) -> process="${comm}" known=${result}`);
-        resolve(result);
-      } catch {
-        console.log(`[PTY] verifyPidOwnership(${pid}) -> error reading /proc/${pid}/comm`);
-        resolve(false);
-      }
-    }
-  }); // Verifies that the PID matches an expected Exeggutor-managed process.
-}
-
-// Scans the database for previously persisted terminal tab process IDs and forcefully terminates any orphaned instances.
-export async function cleanOrphanedPtyProcesses(): Promise<void> {
-  try {
-    const workspaces = db.getWorkspaces(); // Load workspaces from database.
-    console.log(`[PTY] cleanOrphanedPtyProcesses() -> scanning ${workspaces.length} workspaces`);
-    for (const ws of workspaces) {
-      console.log(`[PTY] cleanOrphanedPtyProcesses -> workspace=${ws.id} (${ws.name}) has ${ws.tabs.length} tabs`);
-      for (const tab of ws.tabs) {
-        if (tab.pid) {
-          console.log(`[PTY] cleanOrphanedPtyProcesses -> checking tab=${tab.id} PID=${tab.pid}`);
-          const ownsPid = await verifyPidOwnership(tab.pid); // Flag confirming the PID belongs to an expected process.
-          if (!ownsPid) {
-            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} not owned, clearing record`);
-            try {
-              db.updateTerminalTab(ws.id, tab.id, { pid: undefined }); // Clear stale PID record without killing.
-            } catch (err) {
-              // Safe ignore database write failure.
-            }
-            continue;
-          }
-          console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} owned, sending SIGKILL`);
-          try {
-            process.kill(tab.pid, 'SIGKILL'); // Force terminate the orphaned shell process.
-            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} killed`);
-          } catch (err: any) {
-            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} kill error: ${err.message}`);
-          }
-          try {
-            db.updateTerminalTab(ws.id, tab.id, { pid: undefined }); // Clear the PID record from the database.
-          } catch (err) {
-            // Safe ignore database write failure.
-          }
-        }
-      }
-    }
-  } catch (err: any) {
-    console.log(`[PTY] cleanOrphanedPtyProcesses() -> error: ${err.message}`);
-  }
-}
+import * as pty from 'node-pty';
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { exec } from 'child_process';
+import * as db from './workspaceDb'; // Reference to local sessions JSON database.
+
+export interface TerminalSession {
+  id: string; // The unique tab ID associated with this terminal process.
+  workspaceId: string; // The ID of the workspace that owns this session.
+  ptyProcess: pty.IPty; // The live node-pty process instance.
+  outputBuffer: string[]; // Accumulated recent terminal output lines.
+  lastOutputTime: number; // Unix timestamp of the last stdout chunk received.
+  status: 'Active' | 'Waiting' | 'Idle' | 'Errored'; // Real-time state of the terminal process.
+  lastLinePreview: string; // The single most recent line of terminal output for sidebar observers.
+  onData: (data: string) => void; // Event dispatcher callback for new stdout streams.
+  activeSocket?: any; // The active WebSocket connection associated with this session.
+  broadcastCallback?: () => void; // Optional callback to notify observer of state changes.
+}
+
+const sessions = new Map<string, TerminalSession>(); // Global map cache linking tab IDs to their active persistent TerminalSessions.
+let statusCheckInterval: NodeJS.Timeout | null = null; // Background interval reference for running periodic status audits.
+let spawnLock: Promise<void> | null = null; // Mutex promise ensuring only one PTY spawn executes at a time on Windows.
+let killLock: Promise<void> | null = null; // Mutex promise ensuring only one PTY kill executes at a time on Windows.
+
+// Queries the operating system to recursively find all active child and descendant process IDs of the specified parent process.
+function getDescendants(parentPid: number): Promise<Array<{ pid: number; name: string }>> {
+  console.log(`[PTY] getDescendants(parentPid=${parentPid})`);
+  const p = new Promise<Array<{ pid: number; name: string }>>((resolve) => {
+    const isWin = process.platform === 'win32'; // Flag denoting if the host operating system is Windows.
+    const cmd = isWin ? 'wmic process get ParentProcessId,ProcessId,Name' : 'ps -A -o ppid,pid,comm'; // System command to run.
+    console.log(`[PTY] getDescendants -> running: "${cmd}"`);
+    const runOptions = { windowsHide: true }; // Hide window option.
+    exec(cmd, runOptions, (err, stdout) => {
+      if (err || !stdout) {
+        resolve([]);
+        return;
+      }
+      const lines = stdout.split(/\r?\n/); // Process lines array.
+      const procList: Array<{ pid: number; ppid: number; name: string }> = []; // Registry of all active system processes.
+      for (const line of lines) {
+        const parts = line.trim().split(/\s+/); // Splitted columns.
+        if (parts.length >= 3) {
+          if (isWin) {
+            const ppid = parseInt(parts[0], 10); // Parent process identifier.
+            const pid = parseInt(parts[1], 10); // Target process identifier.
+            const name = parts.slice(2).join(' '); // Process executable name.
+            if (!isNaN(pid) && !isNaN(ppid)) {
+              procList.push({ pid, ppid, name });
+            }
+          } else {
+            const ppid = parseInt(parts[0], 10); // Parent process identifier.
+            const pid = parseInt(parts[1], 10); // Target process identifier.
+            const name = parts.slice(2).join(' '); // Executable name or command line.
+            if (!isNaN(pid) && !isNaN(ppid)) {
+              procList.push({ pid, ppid, name });
+            }
+          }
+        }
+      }
+
+      const descendants: Array<{ pid: number; name: string }> = []; // Flat registry of descendant processes.
+      const queue = [parentPid]; // Queue container for breath-first traversal.
+      const visited = new Set<number>(); // Visited PID tracker to prevent circular reference locks.
+      while (queue.length > 0) {
+        const current = queue.shift()!; // Dequeued parent PID.
+        if (visited.has(current)) {
+          continue;
+        }
+        visited.add(current);
+        const children = procList.filter(p => p.ppid === current); // Direct children matching current process.
+        for (const child of children) {
+          descendants.push({ pid: child.pid, name: child.name });
+          queue.push(child.pid);
+        }
+      }
+      console.log(`[PTY] getDescendants(${parentPid}) -> ${descendants.length} descendants: [${descendants.map(d => `${d.name}(${d.pid})`).join(', ')}]`);
+      resolve(descendants);
+    });
+  }); // Spawns execution promise handle.
+  return p;
+}
+
+// Audits the activity state of all terminal sessions to update active vs idle/waiting states.
+export function startStatusAuditor(broadcastCallback: () => void): void {
+  if (statusCheckInterval) {
+    return;
+  }
+  statusCheckInterval = setInterval(async () => {
+    const now = Date.now(); // The current high resolution timestamp.
+    let changed = false; // Flag to indicate if any session state changed during this audit cycle.
+    
+    const sessionPromises = Array.from(sessions.values()).map(async (session) => {
+      const descendants = await getDescendants(session.ptyProcess.pid); // Retrieved process descendants of the PTY.
+      const utilityNames = new Set([
+        'winpty-agent.exe', 'conhost.exe', 'powershell.exe', 'cmd.exe',
+        'wmic.exe', 'openconsole.exe', 'conconsole.exe', 'bash', 'zsh', 'sh', 'ps'
+      ]); // Process utility names set.
+      
+      const hasActiveProcess = descendants.some(d => {
+        const nameLower = d.name.toLowerCase(); // Lowercased process name.
+        const isUtility = Array.from(utilityNames).some(u => nameLower.includes(u.toLowerCase())); // Flag identifying utility processes.
+        return !isUtility;
+      }); // Verification flag identifying if any non-utility process is running.
+
+      if (!hasActiveProcess) {
+        if (session.status !== 'Idle') {
+          session.status = 'Idle';
+          changed = true;
+        }
+      } else {
+        if (session.status === 'Active' && now - session.lastOutputTime > 2000) {
+          const fullOutput = session.outputBuffer.join(''); // Combined stdout stream of the session.
+          const lines = fullOutput.split(/\r?\n/); // Splitted chunk array.
+          const nonLines = lines.map(l => l.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '').trim()); // Cleaned line array without ANSI.
+          const nonZeroLines = nonLines.filter(l => l.length > 0); // Non-empty cleaned lines.
+          const lastFewLines = nonZeroLines.slice(-5); // Last 5 non-empty output lines.
+          const lastFewTextLower = lastFewLines.join(' ').toLowerCase(); // Combined lowercased string of recent lines.
+          const interactiveGuides = ['tab', 'select', 'enter', 'confirm', 'dismiss', 'arrow', 'esc', 'up/down', '[y/n]']; // Interactive keyboard control terms.
+          const promptIndicators = ['password:', 'password for', 'enter passphrase', 'input:', 'confirm:', 'proceed?']; // Standard CLI input indicators.
+          const hasInteractiveGuides = interactiveGuides.some(guide => lastFewTextLower.includes(guide)); // Flag identifying key guides in output.
+          const hasPromptIndicators = promptIndicators.some(indicator => lastFewTextLower.includes(indicator)); // Flag identifying standard prompts in output.
+          const lastLine = nonZeroLines[nonZeroLines.length - 1] || ''; // The single last line of output.
+          const endsWithQuestion = lastLine.endsWith('?') || lastFewLines.some(l => l.endsWith('?')); // Flag verifying if any recent lines end with a question mark.
+          const isWaiting = hasInteractiveGuides || hasPromptIndicators || endsWithQuestion; // Combined check for form prompt or question.
+          const nextStatus = isWaiting ? 'Waiting' : 'Idle'; // Computed target status mapping.
+          session.status = nextStatus;
+          changed = true;
+        }
+      }
+    }); // Spawns concurrent auditing sessions.
+
+    await Promise.all(sessionPromises);
+    if (changed) {
+      broadcastCallback();
+    }
+  }, 5000); // Trigger auditor check every 5 seconds to reduce wmic process spawn frequency on Windows.
+}
+
+// Spawns a persistent terminal process or retrieves an existing one, matching it to the tab.
+// Uses an async spawn lock to serialize concurrent node-pty process creation on Windows.
+export async function getOrCreatePtySession(
+  workspaceId: string,
+  tabId: string,
+  cwd: string,
+  shellPath?: string,
+  broadcastCallback?: () => void
+): Promise<TerminalSession> {
+  const existing = sessions.get(tabId); // Attempt to retrieve an existing session from the cache.
+  if (existing) {
+    console.log(`[PTY] getOrCreatePtySession -> returning existing session for tab=${tabId} PID=${existing.ptyProcess.pid}`);
+    const foundSession = existing; // Explicit reference to the cached session.
+    return foundSession;
+  }
+
+  console.log(`[PTY] getOrCreatePtySession(workspaceId=${workspaceId}, tabId=${tabId}, cwd=${cwd}, shellPath=${shellPath})`);
+
+  const defaultShell = os.platform() === 'win32' ? 'powershell.exe' : 'bash'; // Choose shell path depending on underlying server OS.
+  const targetShell = shellPath || defaultShell; // Evaluated shell executable to run.
+
+  const ptyArgs: string[] = []; // Arguments passed to the spawned shell.
+  const ptyEnv = { ...process.env } as Record<string, string>; // Environment variables for the spawned process.
+
+  const isWin = os.platform() === 'win32'; // Flag indicating Windows platform.
+  if (isWin) {
+    const guardScript = path.resolve(__dirname, '../scripts/git-guard.ps1');
+    if (fs.existsSync(guardScript)) {
+      ptyArgs.push('-NoLogo', '-NoExit', '-ExecutionPolicy', 'Bypass', '-Command', `. '${guardScript}'`);
+    }
+  } else {
+    const wrapperDir = path.resolve(__dirname, '../git-wrapper');
+    if (fs.existsSync(path.join(wrapperDir, 'git'))) {
+      ptyEnv.PATH = `${wrapperDir}${path.delimiter}${ptyEnv.PATH || ''}`;
+    }
+  }
+
+  // Wait for any in-flight PTY spawn to finish before creating a new one to avoid ConPTY conflicts on Windows.
+  while (spawnLock) {
+    console.log(`[PTY] Spawn lock held, waiting for tab=${tabId}`);
+    await spawnLock;
+  }
+  let releaseLock: () => void = () => {}; // Callback to release the spawn mutex after creation completes, default no-op to avoid TS usage-before-init.
+  spawnLock = new Promise((resolve) => { releaseLock = resolve; });
+
+  console.log(`[PTY] Spawning shell: targetShell="${targetShell}" args=[${ptyArgs.join(', ')}] useConpty=true`);
+  let ptyProcess: pty.IPty; // Reference to the successfully spawned node-pty process.
+  try {
+    ptyProcess = pty.spawn(targetShell, ptyArgs, {
+      name: 'xterm-256color',
+      cols: 80,
+      rows: 24,
+      cwd: cwd,
+      env: ptyEnv,
+      useConpty: true, // Enables the Windows Pseudo Console API for accurate dimension resizes.
+    }); // Spawn the process via node-pty.
+    console.log(`[PTY] Spawned PID=${ptyProcess.pid} for tab=${tabId}`);
+  } catch (err: any) {
+    console.log(`[PTY] Spawn FAILED for tab=${tabId}: ${err.message}. Stack: ${err.stack}`);
+    const spawnErr = new Error(`PTY spawn failed for tab ${tabId}: ${err.message}`); // Error wrapping the spawn failure.
+    spawnLock = null;
+    releaseLock();
+    throw spawnErr;
+  }
+  spawnLock = null;
+  releaseLock();
+
+  const newSession: TerminalSession = {
+    id: tabId,
+    workspaceId: workspaceId,
+    ptyProcess: ptyProcess,
+    outputBuffer: [],
+    lastOutputTime: Date.now(),
+    status: 'Idle',
+    lastLinePreview: '',
+    onData: () => {},
+    broadcastCallback: broadcastCallback,
+  }; // The new terminal session schema instance mapping this tab.
+
+  sessions.set(tabId, newSession);
+
+  // Save process PID to database for future orphan recovery.
+  try {
+    db.updateTerminalTab(workspaceId, tabId, { pid: ptyProcess.pid });
+  } catch (err) {
+    // Safe ignore database update failure.
+  }
+
+  ptyProcess.onData(data => {
+    newSession.lastOutputTime = Date.now();
+    
+    const maxBufferLines = 1000; // Limit total cached rows in memory to save memory usage.
+    newSession.outputBuffer.push(data);
+    if (newSession.outputBuffer.length > maxBufferLines) {
+      newSession.outputBuffer.shift();
+    }
+
+    const lines = data.split(/\r?\n/); // Splitted chunk array.
+    const lastNonEmpty = lines.filter(l => l.trim().length > 0).pop(); // The last non-empty line of text.
+    if (lastNonEmpty) {
+      const cleanLine = lastNonEmpty.replace(/[\u001b\u009b][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]/g, '').trim(); // Remove ANSI terminal escape codes.
+      if (cleanLine.length > 0) {
+        newSession.lastLinePreview = cleanLine.substring(0, 100);
+      }
+    }
+
+    const oldStatus = newSession.status; // Preserve original status before computation.
+    newSession.status = 'Active'; // Mark status as active immediately when receiving new data.
+
+    newSession.onData(data);
+
+    if (oldStatus !== newSession.status && broadcastCallback) {
+      broadcastCallback();
+    }
+  });
+
+  ptyProcess.onExit(res => {
+    newSession.status = res.exitCode === 0 ? 'Idle' : 'Errored';
+    if (broadcastCallback) {
+      broadcastCallback();
+    }
+  });
+
+  const createdSession = newSession; // Explicit reference to return.
+  return createdSession;
+}
+
+// Resizes the terminal process row and column dimensions.
+export function resizePtySession(tabId: string, cols: number, rows: number): void {
+  const session = sessions.get(tabId); // Look up session by ID.
+  if (session && typeof cols === 'number' && typeof rows === 'number' && cols > 0 && rows > 0) {
+    const parsedCols = Math.max(Math.floor(cols), 40); // Ensures PTY size is at least 40 columns wide.
+    const parsedRows = Math.max(Math.floor(rows), 10); // Ensures PTY size is at least 10 rows high.
+    if (parsedCols > 0 && parsedRows > 0) {
+      session.ptyProcess.resize(parsedCols, parsedRows);
+    }
+  }
+}
+
+// Write input data directly to the active terminal process.
+// Does not change the session status — the periodic auditor handles status transitions,
+// preventing rapid Idle↔Active flickering that occurred on every keystroke.
+export function writeToPtySession(tabId: string, data: string): void {
+  const session = sessions.get(tabId); // Look up session by ID.
+  if (session) {
+    session.ptyProcess.write(data);
+  }
+}
+
+// Forces the termination of a terminal session and frees system process resources.
+// Serializes concurrent kills on Windows to avoid overlapping conhost termination window flashes.
+export async function killPtySession(tabId: string): Promise<void> {
+  const session = sessions.get(tabId); // Find session by tab ID.
+  if (session) {
+    console.log(`[PTY] killPtySession(tabId=${tabId}) -> killing PID=${session.ptyProcess.pid}`);
+    // Wait for any in-flight PTY kill to finish before terminating this one to avoid ConPTY conflicts on Windows.
+    while (killLock) {
+      console.log(`[PTY] Kill lock held, waiting for tab=${tabId}`);
+      await killLock;
+    }
+    let releaseKillLock: () => void = () => {}; // Callback to release the kill mutex after termination completes.
+    killLock = new Promise((resolve) => { releaseKillLock = resolve; });
+
+    try {
+      session.ptyProcess.kill();
+      console.log(`[PTY] killPtySession(tabId=${tabId}) -> kill OK`);
+    } catch (err: any) {
+      console.log(`[PTY] killPtySession(tabId=${tabId}) -> kill error: ${err.message}`);
+    } finally {
+      killLock = null;
+      releaseKillLock();
+    }
+    try {
+      db.updateTerminalTab(session.workspaceId, tabId, { pid: undefined }); // Clear the PID record from the database.
+    } catch (err) {
+      // Safe ignore database write failure.
+    }
+    sessions.delete(tabId);
+    console.log(`[PTY] killPtySession(tabId=${tabId}) -> session removed from map`);
+  } else {
+    console.log(`[PTY] killPtySession(tabId=${tabId}) -> no active session found`);
+  }
+}
+
+// Retrieves all terminal session descriptors currently managed by the backend.
+export function getAllSessions(): Array<{ id: string; workspaceId: string; status: string; preview: string }> {
+  const list: Array<{ id: string; workspaceId: string; status: string; preview: string }> = []; // Return sessions descriptors.
+  sessions.forEach(s => {
+    list.push({
+      id: s.id,
+      workspaceId: s.workspaceId,
+      status: s.status,
+      preview: s.lastLinePreview,
+    });
+  });
+  return list;
+}
+
+// Verifies that a given PID belongs to an expected Exeggutor-managed process to avoid killing unrelated recycled PIDs.
+function verifyPidOwnership(pid: number): Promise<boolean> {
+  console.log(`[PTY] verifyPidOwnership(pid=${pid})`);
+  return new Promise((resolve) => {
+    const isWin = process.platform === 'win32'; // Flag indicating Windows platform.
+    if (isWin) {
+      console.log(`[PTY] verifyPidOwnership -> running: tasklist /FI "PID eq ${pid}"`);
+      exec(`tasklist /FI "PID eq ${pid}" /FO CSV /NH`, { windowsHide: true }, (err, stdout) => {
+        if (err || !stdout) {
+          resolve(false);
+          return;
+        }
+        const nameMatch = stdout.match(/"([^"]+)"/); // Capture the process executable name from CSV output.
+        if (!nameMatch) {
+          resolve(false);
+          return;
+        }
+        const name = nameMatch[1].toLowerCase(); // Process name from tasklist.
+        const knownNames = ['node.exe', 'powershell.exe', 'cmd.exe', 'bash.exe', 'wmic.exe', 'conhost.exe'];
+        const result = knownNames.some(k => name.includes(k));
+        console.log(`[PTY] verifyPidOwnership(${pid}) -> process="${name}" known=${result}`);
+        resolve(result);
+      }); // Spawn tasklist to verify process identity.
+    } else {
+      try {
+        const comm = fs.readFileSync(`/proc/${pid}/comm`, 'utf8').trim(); // Process command name from proc filesystem.
+        const knownNames = ['node', 'bash', 'zsh', 'sh', 'dash', 'powershell'];
+        const result = knownNames.includes(comm);
+        console.log(`[PTY] verifyPidOwnership(${pid}) -> process="${comm}" known=${result}`);
+        resolve(result);
+      } catch {
+        console.log(`[PTY] verifyPidOwnership(${pid}) -> error reading /proc/${pid}/comm`);
+        resolve(false);
+      }
+    }
+  }); // Verifies that the PID matches an expected Exeggutor-managed process.
+}
+
+// Scans the database for previously persisted terminal tab process IDs and forcefully terminates any orphaned instances.
+export async function cleanOrphanedPtyProcesses(): Promise<void> {
+  try {
+    const workspaces = db.getWorkspaces(); // Load workspaces from database.
+    console.log(`[PTY] cleanOrphanedPtyProcesses() -> scanning ${workspaces.length} workspaces`);
+    for (const ws of workspaces) {
+      console.log(`[PTY] cleanOrphanedPtyProcesses -> workspace=${ws.id} (${ws.name}) has ${ws.tabs.length} tabs`);
+      for (const tab of ws.tabs) {
+        if (tab.pid) {
+          console.log(`[PTY] cleanOrphanedPtyProcesses -> checking tab=${tab.id} PID=${tab.pid}`);
+          const ownsPid = await verifyPidOwnership(tab.pid); // Flag confirming the PID belongs to an expected process.
+          if (!ownsPid) {
+            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} not owned, clearing record`);
+            try {
+              db.updateTerminalTab(ws.id, tab.id, { pid: undefined }); // Clear stale PID record without killing.
+            } catch (err) {
+              // Safe ignore database write failure.
+            }
+            continue;
+          }
+          console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} owned, sending SIGKILL`);
+          try {
+            process.kill(tab.pid, 'SIGKILL'); // Force terminate the orphaned shell process.
+            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} killed`);
+          } catch (err: any) {
+            console.log(`[PTY] cleanOrphanedPtyProcesses -> tab=${tab.id} PID=${tab.pid} kill error: ${err.message}`);
+          }
+          try {
+            db.updateTerminalTab(ws.id, tab.id, { pid: undefined }); // Clear the PID record from the database.
+          } catch (err) {
+            // Safe ignore database write failure.
+          }
+        }
+      }
+    }
+  } catch (err: any) {
+    console.log(`[PTY] cleanOrphanedPtyProcesses() -> error: ${err.message}`);
+  }
+}