@ts47andres/exeggutor 1.1.4 → 1.1.5

package/packages/backend/src/index.ts

@@ -1,554 +1,554 @@
-import fastify, { FastifyInstance } from 'fastify';
-import fastifyCors from '@fastify/cors';
-import fastifyWebsocket from '@fastify/websocket';
-import fastifyStatic from '@fastify/static';
-import * as path from 'path';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as crypto from 'crypto';
-import * as db from './workspaceDb';
-import * as git from './gitWorktree';
-import * as pty from './ptyManager';
-import * as tailscale from './tailscale';
-
-const PORT = parseInt(process.env.EXEGGUTOR_BACKEND_PORT || '17492', 10); // Backend API port from env or default.
-const FRONTEND_DIST = process.env.EXEGGUTOR_FRONTEND_DIST || ''; // Path to built frontend dist/ folder.
-const configPath = path.resolve(os.homedir(), '.exeggutor.json'); // Path to CLI config file.
-let authToken = process.env.EXEGGUTOR_AUTH_TOKEN || ''; // Active authorization token.
-const TAILSCALE_MODE = process.env.EXEGGUTOR_TAILSCALE === '1'; // Whether to expose the server over Tailscale.
-try {
-  if (fs.existsSync(configPath)) {
-    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); // Loaded configuration settings.
-    if (cfg.authToken) {
-      authToken = cfg.authToken;
-    }
-  }
-} catch (_) {
-  // Safe ignore config load errors.
-}
-
-// Determine the host binding for the server.
-function resolveListenHost(): string {
-  if (TAILSCALE_MODE) {
-    return '0.0.0.0'; // Bind to all interfaces so Tailscale can forward traffic.
-  }
-  return '127.0.0.1'; // Local-only binding for security.
-}
-
-const server: FastifyInstance = fastify({ logger: true }); // Fastify server instance running local services with logging enabled.
-const observerSockets = new Set<any>(); // Registry containing all active WebSocket connections for the observer sidebar.
-const sessionCodes = new Map<string, { token: string; expires: number }>(); // One-time session codes for dashboard authentication exchange.
-
-// Broadcasts the latest status of all terminal sessions to all observer socket clients.
-function broadcastObserverUpdate(): void {
-  const payload = JSON.stringify({
-    type: 'observer',
-    sessions: pty.getAllSessions(),
-  }); // Serialized payload containing status mapping of all terminal sessions.
-  observerSockets.forEach(ws => {
-    try {
-      ws.send(payload);
-    } catch (err) {
-      // Clean up failed sockets.
-    }
-  });
-}
-
-// Registers HTTP routes, WebSockets endpoints, and starts the Fastify service.
-async function bootstrap(): Promise<void> {
-  // Clean up any orphaned terminal shell processes from previous runs.
-  await pty.cleanOrphanedPtyProcesses();
-
-  await server.register(fastifyCors, { origin: true });
-  await server.register(fastifyWebsocket);
-
-  server.addHook('preHandler', async (request, reply) => {
-    const url = request.url; // Target request URL path.
-    if ((url.startsWith('/api') || url.startsWith('/ws')) && url !== '/api/auth/exchange-session') {
-      let token = (request.query as any)?.token; // Token extracted from query parameter.
-      if (!token) {
-        const authHeader = request.headers.authorization; // Auth header content.
-        if (authHeader && authHeader.startsWith('Bearer ')) {
-          token = authHeader.substring(7);
-        }
-      }
-      if (!authToken || token !== authToken) {
-        reply.status(401).send({ error: 'Unauthorized' });
-        return reply;
-      }
-    }
-  }); // Registers authentication pre-handler hook.
-
-  // Serve built frontend statically when EXEGGUTOR_FRONTEND_DIST is set (production mode).
-  if (FRONTEND_DIST && fs.existsSync(FRONTEND_DIST)) {
-    await server.register(fastifyStatic, {
-      root: FRONTEND_DIST,
-      wildcard: false,
-      prefix: '/',
-    });
-    // SPA fallback: serve index.html for all non-API, non-WS routes.
-    server.setNotFoundHandler((request, reply) => {
-      if (request.url.startsWith('/api') || request.url.startsWith('/ws')) {
-        reply.status(404).send({ error: 'Not found' });
-      } else {
-        const indexPath = path.join(FRONTEND_DIST, 'index.html');
-        if (fs.existsSync(indexPath)) {
-          reply.type('text/html').send(fs.readFileSync(indexPath, 'utf8'));
-        } else {
-          reply.status(404).send('Not found');
-        }
-      }
-    });
-  }
-
-  pty.startStatusAuditor(broadcastObserverUpdate);
-
-  server.post('/api/auth/issue-session', async (request, reply) => {
-    const code = crypto.randomBytes(16).toString('hex'); // Unpredictable one-time session code.
-    sessionCodes.set(code, { token: authToken, expires: Date.now() + 30000 }); // Code valid for 30 seconds.
-    return { code };
-  });
-
-  server.post('/api/auth/exchange-session', async (request, reply) => {
-    const { code } = request.body as any; // Session code from the URL.
-    const entry = sessionCodes.get(code); // Lookup matching code entry.
-    if (!entry || entry.expires < Date.now()) {
-      reply.status(401).send({ error: 'Invalid or expired session code' });
-      return reply;
-    }
-    sessionCodes.delete(code); // Invalidate code after use.
-    return { token: entry.token };
-  });
-
-  setInterval(() => {
-    const now = Date.now(); // Current timestamp.
-    sessionCodes.forEach((entry, code) => {
-      if (entry.expires < now) {
-        sessionCodes.delete(code);
-      }
-    }); // Purge expired session codes every 60 seconds.
-  }, 60000);
-
-  server.get('/api/workspaces', async (request, reply) => {
-    const list = db.getWorkspaces(); // Workspace list from database.
-    return list;
-  });
-
-  server.post<{ Body: { name: string; path: string } }>(
-    '/api/workspaces',
-    async (request, reply) => {
-      const { name, path: folderPath } = request.body; // Deconstructed parameters from request body.
-      if (!name || typeof name !== 'string' || name.trim().length === 0) {
-        reply.status(400);
-        return { error: 'Workspace name is required' };
-      }
-      if (name.trim().length > 100) {
-        reply.status(400);
-        return { error: 'Workspace name must be 100 characters or fewer' };
-      }
-      if (!folderPath || typeof folderPath !== 'string' || folderPath.trim().length === 0) {
-        reply.status(400);
-        return { error: 'Workspace path is required' };
-      }
-      const resolvedPath = path.resolve(folderPath.trim()); // Resolved absolute target path.
-      if (!fs.existsSync(resolvedPath)) {
-        reply.status(400);
-        return { error: 'Workspace path does not exist' };
-      }
-      if (!fs.statSync(resolvedPath).isDirectory()) {
-        reply.status(400);
-        return { error: 'Workspace path must be a directory' };
-      }
-      try {
-        fs.accessSync(resolvedPath, fs.constants.R_OK);
-      } catch {
-        reply.status(400);
-        return { error: 'Workspace path is not readable' };
-      }
-      const createdWs = db.createWorkspace(name.trim(), resolvedPath); // Reference to the created workspace.
-      return createdWs;
-    }
-  );
-
-  server.delete<{ Params: { id: string } }>('/api/workspaces/:id', async (request, reply) => {
-    const id = request.params.id; // Target workspace ID.
-    console.log(`[API] DELETE /api/workspaces/${id} -> deleting workspace`);
-    const wsList = db.getWorkspaces(); // Entire registered workspaces array.
-    const targetWs = wsList.find(w => w.id === id); // Found workspace object matching the target ID.
-    if (targetWs) {
-      console.log(`[API] Deleting workspace "${targetWs.name}" (id=${id}) with ${targetWs.tabs.length} tabs`);
-      await Promise.all(
-        targetWs.tabs.map(async tab => {
-          console.log(`[API] Cleaning up tab ${tab.id} for workspace delete`);
-          await pty.killPtySession(tab.id);
-          if (tab.worktreePath) {
-            try {
-              await git.removeGitWorktree(targetWs.path, tab.worktreePath);
-            } catch (err) {
-              // Ignore pruning issues.
-            }
-          }
-        })
-      ); // Run PTY shutdowns and worktree cleanups concurrently.
-      db.deleteWorkspace(id);
-      console.log(`[API] Workspace ${id} deleted`);
-    }
-    const successResp = { success: true }; // Server confirmation object.
-    return successResp;
-  });
-
-  server.put<{ Params: { id: string }; Body: Partial<Omit<db.Workspace, 'id' | 'tabs'>> }>(
-    '/api/workspaces/:id',
-    async (request, reply) => {
-      const id = request.params.id; // Target workspace ID.
-      const updates = request.body; // Updated attributes from body.
-      const updated = db.updateWorkspace(id, updates); // Workspace with applied patches.
-      const returnResult = updated; // Refactored return workspace.
-      return returnResult;
-    }
-  );
-
-  const MAX_TABS_PER_WORKSPACE = 4; // Maximum number of terminal tabs allowed per workspace.
-
-  server.post<{ Params: { id: string }; Body: { name: string; shell?: string } }>(
-    '/api/workspaces/:id/tabs',
-    async (request, reply) => {
-      const id = request.params.id; // Parent workspace ID.
-      const { name, shell } = request.body; // Input body variables.
-      console.log(`[API] POST /api/workspaces/${id}/tabs -> creating tab name="${name}" shell="${shell}"`);
-      const targetWs = db.getWorkspaces().find(w => w.id === id); // Find matching workspace database entry.
-      if (!targetWs) {
-        reply.status(404);
-        const errorResp = { error: 'Workspace not found' }; // Missing workspace error.
-        return errorResp;
-      }
-      if (targetWs.tabs.length >= MAX_TABS_PER_WORKSPACE) {
-        reply.status(400);
-        const errorResp = { error: `Maximum ${MAX_TABS_PER_WORKSPACE} terminal tabs per workspace` }; // Tab limit error.
-        return errorResp;
-      }
-      const tab = db.createTerminalTab(id, name, targetWs.path, shell); // New tab object created.
-      if (tab) {
-        console.log(`[API] Tab created: id=${tab.id} name="${name}" cwd=${tab.cwd}`);
-      }
-      const returnResult = tab; // Created tab descriptor.
-      return returnResult;
-    }
-  );
-
-  server.put<{ Params: { id: string; tabId: string }; Body: { name?: string; branch?: string } }>(
-    '/api/workspaces/:id/tabs/:tabId',
-    async (request, reply) => {
-      const { id, tabId } = request.params; // Workspace and tab parameter keys.
-      const { name, branch } = request.body; // Extracted updates.
-      console.log(`[API] PUT /api/workspaces/${id}/tabs/${tabId} -> name="${name}" branch="${branch}"`);
-      const targetWs = db.getWorkspaces().find(w => w.id === id); // Target workspace object.
-      if (!targetWs) {
-        reply.status(404);
-        const errorResp = { error: 'Workspace not found' }; // Error payload.
-        return errorResp;
-      }
-      const tab = targetWs.tabs.find(t => t.id === tabId); // Selected terminal tab.
-      if (!tab) {
-        reply.status(404);
-        const errorResp = { error: 'Terminal tab not found' }; // Error payload.
-        return errorResp;
-      }
-
-      let worktreePath = tab.worktreePath; // Preserve current worktree path reference.
-      let newCwd = tab.cwd; // Preserve current target current working directory.
-
-      if (branch !== undefined && branch !== tab.branch) {
-        console.log(`[API] Branch change detected for tab ${tabId}: "${tab.branch}" -> "${branch}", killing PTY`);
-        await pty.killPtySession(tabId);
-        if (tab.worktreePath) {
-          try {
-            await git.removeGitWorktree(targetWs.path, tab.worktreePath);
-          } catch (err) {
-            // Prune error.
-          }
-          worktreePath = undefined;
-          newCwd = targetWs.path;
-        }
-        if (branch && branch.trim().length > 0) {
-          try {
-            const wPath = await git.setupGitWorktree(targetWs.path, branch); // Spawn isolated git worktree folder.
-            worktreePath = wPath;
-            newCwd = wPath;
-          } catch (err: any) {
-            reply.status(400);
-            const errorResp = { error: err.message || 'Failed to setup git worktree' }; // Setup error.
-            return errorResp;
-          }
-        } else {
-          newCwd = targetWs.path;
-        }
-      }
-
-      const updates: Partial<db.TerminalTab> = {}; // Config updates map.
-      if (name !== undefined) {
-        updates.name = name;
-      }
-      if (branch !== undefined) {
-        updates.branch = branch ? branch : undefined;
-        updates.worktreePath = worktreePath;
-        updates.cwd = newCwd;
-      }
-
-      const updated = db.updateTerminalTab(id, tabId, updates); // Flush updates to sessions database.
-      const returnResult = updated; // Updated tab object.
-      return returnResult;
-    }
-  );
-
-  server.post<{ Params: { id: string; tabId: string }; Body: { name: string } }>(
-    '/api/workspaces/:id/tabs/:tabId/branches',
-    async (request, reply) => {
-      const { id, tabId } = request.params; // Workspace and tab keys.
-      const { name: branchName } = request.body; // New branch name.
-      console.log(`[API] POST /api/workspaces/${id}/tabs/${tabId}/branches -> branch="${branchName}"`);
-      const targetWs = db.getWorkspaces().find(w => w.id === id); // Found workspace.
-      if (!targetWs) {
-        reply.status(404);
-        const errorResp = { error: 'Workspace not found' }; // Error payload.
-        return errorResp;
-      }
-      const tab = targetWs.tabs.find(t => t.id === tabId); // Target tab config.
-      if (!tab) {
-        reply.status(404);
-        const errorResp = { error: 'Terminal tab not found' }; // Error.
-        return errorResp;
-      }
-      try {
-        await git.createBranch(targetWs.path, branchName);
-        await pty.killPtySession(tabId);
-        if (tab.worktreePath) {
-          try {
-            await git.removeGitWorktree(targetWs.path, tab.worktreePath);
-          } catch (err) {
-            // Prune error.
-          }
-        }
-        const wPath = await git.setupGitWorktree(targetWs.path, branchName); // Create new worktree directly.
-        const updated = db.updateTerminalTab(id, tabId, {
-          branch: branchName,
-          worktreePath: wPath,
-          cwd: wPath,
-        }); // Apply updates to database tab.
-        const returnResult = updated; // Tab payload.
-        return returnResult;
-      } catch (err: any) {
-        reply.status(400);
-        const errorResp = { error: err.message || 'Failed to create git branch' }; // Error payload.
-        return errorResp;
-      }
-    }
-  );
-
-  server.delete<{ Params: { id: string; tabId: string } }>(
-    '/api/workspaces/:id/tabs/:tabId',
-    async (request, reply) => {
-      const { id, tabId } = request.params; // Tab and workspace parameters.
-      console.log(`[API] DELETE /api/workspaces/${id}/tabs/${tabId} -> deleting tab`);
-      const targetWs = db.getWorkspaces().find(w => w.id === id); // Found workspace.
-      if (targetWs) {
-        const tab = targetWs.tabs.find(t => t.id === tabId); // Target tab config.
-        console.log(`[API] Killing PTY and cleaning up worktree for tab ${tabId}`);
-        await pty.killPtySession(tabId);
-        if (tab && tab.worktreePath) {
-          try {
-            await git.removeGitWorktree(targetWs.path, tab.worktreePath);
-          } catch (err) {
-            // Ignore.
-          }
-        }
-        db.deleteTerminalTab(id, tabId);
-        console.log(`[API] Tab ${tabId} deleted`);
-      }
-      const successResp = { success: true }; // Operation complete.
-      return successResp;
-    }
-  );
-
-  server.get<{ Params: { id: string } }>('/api/workspaces/:id/git/branches', async (request, reply) => {
-    const id = request.params.id; // Target workspace ID.
-    const ws = db.getWorkspaces().find(w => w.id === id); // Target workspace instance.
-    if (!ws) {
-      reply.status(404);
-      const errorResp = { error: 'Workspace not found' }; // Error workspace message.
-      return errorResp;
-    }
-    try {
-      const branches = await git.getBranches(ws.path); // Retrieve active branch array from workspace folder.
-      const returnResult = branches; // Branches array result.
-      return returnResult;
-    } catch (err: any) {
-      reply.status(500);
-      const errorResp = { error: err.message || 'Failed to query git branches' }; // Error payload.
-      return errorResp;
-    }
-  });
-
-  server.get<{ Querystring: { name: string } }>('/api/branches/in-use', async (request, reply) => {
-    const { name } = request.query; // Branch name to check.
-    const allWorkspaces = db.getWorkspaces(); // All registered workspaces.
-    let inUse = false; // Default safety flag.
-    for (const ws of allWorkspaces) {
-      for (const tab of ws.tabs) {
-        if (tab.branch === name) {
-          inUse = true;
-          break;
-        }
-      }
-      if (inUse) { break; }
-    }
-    const result = { inUse }; // Response payload.
-    return result;
-  });
-
-  // Returns the current Tailscale status and connection info for the server.
-  server.get('/api/tailscale/status', async (request, reply) => {
-    const installed = tailscale.isTailscaleInstalled(); // Whether the tailscale binary exists on PATH.
-    const info = installed ? tailscale.getTailscaleInfo() : null; // Parsed tailscale status, null if not connected.
-    return {
-      installed,
-      connected: info !== null,
-      tailscale: info,
-      tailscaleMode: TAILSCALE_MODE,
-    };
-  });
-
-  server.get('/api/browse', async (request, reply) => {
-    try {
-      const folder = await git.showFolderPicker();
-      if (!folder) {
-        // User cancelled the dialog — not an error.
-        return { path: '', cancelled: true };
-      }
-      return { path: folder };
-    } catch (err: any) {
-      reply.status(500);
-      return { path: '', error: err.message || 'Failed to open folder picker' };
-    }
-  });
-
-  server.route({
-    method: 'GET',
-    url: '/ws/observer',
-    handler: (request, reply) => {
-      reply.status(400).send('WebSocket connection expected');
-    },
-    wsHandler: (connection, req) => {
-      observerSockets.add(connection);
-      const initialPayload = JSON.stringify({
-        type: 'observer',
-        sessions: pty.getAllSessions(),
-      }); // Initial data load payload for new client.
-      connection.send(initialPayload);
-      connection.on('close', () => {
-        observerSockets.delete(connection);
-      });
-    },
-  });
-
-  server.route({
-    method: 'GET',
-    url: '/ws/terminal/:tabId',
-    handler: (request, reply) => {
-      reply.status(400).send('WebSocket connection expected');
-    },
-    wsHandler: async (connection, req) => {
-      const tabId = (req.params as any).tabId; // Extract tabId from parameters.
-      console.log(`[WS] Terminal WebSocket connect: tabId=${tabId}`);
-      const workspaces = db.getWorkspaces(); // Load workspaces registry.
-      let activeTab: db.TerminalTab | undefined = undefined; // Matches the target active tab.
-      let activeWs: db.Workspace | undefined = undefined; // Matches the parent workspace containing the tab.
-      for (const ws of workspaces) {
-        const found = ws.tabs.find(t => t.id === tabId); // Match lookup.
-        if (found) {
-          activeTab = found;
-          activeWs = ws;
-          break;
-        }
-      }
-      if (!activeTab || !activeWs) {
-        console.log(`[WS] Terminal tab ${tabId} not found in any workspace, closing connection`);
-        connection.close(4001, 'Terminal tab not found');
-        return;
-      }
-      console.log(`[WS] Calling getOrCreatePtySession for tab ${tabId} (workspace=${activeWs.name}, cwd=${activeTab.cwd})`);
-      let session: pty.TerminalSession; // Reference to the created or retrieved terminal session.
-      try {
-        session = await pty.getOrCreatePtySession(
-          activeWs.id,
-          activeTab.id,
-          activeTab.cwd,
-          activeTab.shell,
-          broadcastObserverUpdate
-        ); // Await spawn or attach of persistent session process (serialized on Windows).
-      } catch (err: any) {
-        console.log(`[WS] getOrCreatePtySession failed for tab ${tabId}: ${err.message}`);
-        connection.close(4002, 'Terminal session creation failed');
-        return;
-      }
-      console.log(`[WS] getOrCreatePtySession returned for tab ${tabId}, PID=${session.ptyProcess.pid}`);
-
-      session.activeSocket = connection; // Register the newly connected socket as the active connection.
-
-      session.outputBuffer.forEach(chunk => {
-        connection.send(chunk);
-      });
-
-      // Handles incoming data from the persistent PTY process by sending it over the WebSocket.
-      session.onData = (data: string) => {
-        try {
-          if (session.activeSocket === connection) {
-            connection.send(data);
-          }
-        } catch (err) {
-          // Socket write failed.
-        }
-      };
-
-      // Receives input and resize instructions from the WebSocket and forwards them to the PTY session.
-      connection.on('message', (messageData: any) => {
-        const rawMessage = messageData.toString(); // Normalized string representation of the incoming socket message.
-        try {
-          const parsed = JSON.parse(rawMessage); // Parsed client websocket message.
-          if (parsed && parsed.type === 'resize') {
-            pty.resizePtySession(tabId, parsed.cols, parsed.rows);
-          } else if (parsed && parsed.type === 'input') {
-            pty.writeToPtySession(tabId, parsed.data);
-          }
-        } catch (err) {
-          // Ignore invalid JSON payloads to prevent writing garbage or raw JSON controls to the shell.
-        }
-      });
-
-      // Disconnects the WebSocket connection and marks the PTY session active socket as empty.
-      connection.on('close', () => {
-        console.log(`[WS] Terminal WebSocket disconnect: tabId=${tabId}`);
-        if (session.activeSocket === connection) {
-          session.activeSocket = undefined;
-          session.onData = () => {};
-        }
-      });
-    },
-  });
-
-  const listenHost = resolveListenHost(); // Network interface to bind the server to.
-  await server.listen({ port: PORT, host: listenHost });
-  const tailscaleInfo = TAILSCALE_MODE ? tailscale.getTailscaleInfo() : null; // Information about the current Tailscale connection.
-  if (tailscaleInfo) {
-    console.log(`Tailscale URL: http://${tailscaleInfo.ip}:${PORT}`);
-    if (tailscaleInfo.dnsName) {
-      console.log(`Tailscale DNS: https://${tailscaleInfo.dnsName}:${PORT}`);
-    }
-  }
-  console.log(`Backend daemon is listening on port ${PORT} (bound to ${listenHost})`);
-}
-
-bootstrap().catch(err => {
-  console.error('Fatal initialization error:', err);
-  process.exit(1);
-});
+import fastify, { FastifyInstance } from 'fastify';
+import fastifyCors from '@fastify/cors';
+import fastifyWebsocket from '@fastify/websocket';
+import fastifyStatic from '@fastify/static';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as crypto from 'crypto';
+import * as db from './workspaceDb';
+import * as git from './gitWorktree';
+import * as pty from './ptyManager';
+import * as tailscale from './tailscale';
+
+const PORT = parseInt(process.env.EXEGGUTOR_BACKEND_PORT || '17492', 10); // Backend API port from env or default.
+const FRONTEND_DIST = process.env.EXEGGUTOR_FRONTEND_DIST || ''; // Path to built frontend dist/ folder.
+const configPath = path.resolve(os.homedir(), '.exeggutor.json'); // Path to CLI config file.
+let authToken = process.env.EXEGGUTOR_AUTH_TOKEN || ''; // Active authorization token.
+const TAILSCALE_MODE = process.env.EXEGGUTOR_TAILSCALE === '1'; // Whether to expose the server over Tailscale.
+try {
+  if (fs.existsSync(configPath)) {
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8')); // Loaded configuration settings.
+    if (cfg.authToken) {
+      authToken = cfg.authToken;
+    }
+  }
+} catch (_) {
+  // Safe ignore config load errors.
+}
+
+// Determine the host binding for the server.
+function resolveListenHost(): string {
+  if (TAILSCALE_MODE) {
+    return '0.0.0.0'; // Bind to all interfaces so Tailscale can forward traffic.
+  }
+  return '127.0.0.1'; // Local-only binding for security.
+}
+
+const server: FastifyInstance = fastify({ logger: true }); // Fastify server instance running local services with logging enabled.
+const observerSockets = new Set<any>(); // Registry containing all active WebSocket connections for the observer sidebar.
+const sessionCodes = new Map<string, { token: string; expires: number }>(); // One-time session codes for dashboard authentication exchange.
+
+// Broadcasts the latest status of all terminal sessions to all observer socket clients.
+function broadcastObserverUpdate(): void {
+  const payload = JSON.stringify({
+    type: 'observer',
+    sessions: pty.getAllSessions(),
+  }); // Serialized payload containing status mapping of all terminal sessions.
+  observerSockets.forEach(ws => {
+    try {
+      ws.send(payload);
+    } catch (err) {
+      // Clean up failed sockets.
+    }
+  });
+}
+
+// Registers HTTP routes, WebSockets endpoints, and starts the Fastify service.
+async function bootstrap(): Promise<void> {
+  // Clean up any orphaned terminal shell processes from previous runs.
+  await pty.cleanOrphanedPtyProcesses();
+
+  await server.register(fastifyCors, { origin: true });
+  await server.register(fastifyWebsocket);
+
+  server.addHook('preHandler', async (request, reply) => {
+    const url = request.url; // Target request URL path.
+    if ((url.startsWith('/api') || url.startsWith('/ws')) && url !== '/api/auth/exchange-session') {
+      let token = (request.query as any)?.token; // Token extracted from query parameter.
+      if (!token) {
+        const authHeader = request.headers.authorization; // Auth header content.
+        if (authHeader && authHeader.startsWith('Bearer ')) {
+          token = authHeader.substring(7);
+        }
+      }
+      if (!authToken || token !== authToken) {
+        reply.status(401).send({ error: 'Unauthorized' });
+        return reply;
+      }
+    }
+  }); // Registers authentication pre-handler hook.
+
+  // Serve built frontend statically when EXEGGUTOR_FRONTEND_DIST is set (production mode).
+  if (FRONTEND_DIST && fs.existsSync(FRONTEND_DIST)) {
+    await server.register(fastifyStatic, {
+      root: FRONTEND_DIST,
+      wildcard: false,
+      prefix: '/',
+    });
+    // SPA fallback: serve index.html for all non-API, non-WS routes.
+    server.setNotFoundHandler((request, reply) => {
+      if (request.url.startsWith('/api') || request.url.startsWith('/ws')) {
+        reply.status(404).send({ error: 'Not found' });
+      } else {
+        const indexPath = path.join(FRONTEND_DIST, 'index.html');
+        if (fs.existsSync(indexPath)) {
+          reply.type('text/html').send(fs.readFileSync(indexPath, 'utf8'));
+        } else {
+          reply.status(404).send('Not found');
+        }
+      }
+    });
+  }
+
+  pty.startStatusAuditor(broadcastObserverUpdate);
+
+  server.post('/api/auth/issue-session', async (request, reply) => {
+    const code = crypto.randomBytes(16).toString('hex'); // Unpredictable one-time session code.
+    sessionCodes.set(code, { token: authToken, expires: Date.now() + 30000 }); // Code valid for 30 seconds.
+    return { code };
+  });
+
+  server.post('/api/auth/exchange-session', async (request, reply) => {
+    const { code } = request.body as any; // Session code from the URL.
+    const entry = sessionCodes.get(code); // Lookup matching code entry.
+    if (!entry || entry.expires < Date.now()) {
+      reply.status(401).send({ error: 'Invalid or expired session code' });
+      return reply;
+    }
+    sessionCodes.delete(code); // Invalidate code after use.
+    return { token: entry.token };
+  });
+
+  setInterval(() => {
+    const now = Date.now(); // Current timestamp.
+    sessionCodes.forEach((entry, code) => {
+      if (entry.expires < now) {
+        sessionCodes.delete(code);
+      }
+    }); // Purge expired session codes every 60 seconds.
+  }, 60000);
+
+  server.get('/api/workspaces', async (request, reply) => {
+    const list = db.getWorkspaces(); // Workspace list from database.
+    return list;
+  });
+
+  server.post<{ Body: { name: string; path: string } }>(
+    '/api/workspaces',
+    async (request, reply) => {
+      const { name, path: folderPath } = request.body; // Deconstructed parameters from request body.
+      if (!name || typeof name !== 'string' || name.trim().length === 0) {
+        reply.status(400);
+        return { error: 'Workspace name is required' };
+      }
+      if (name.trim().length > 100) {
+        reply.status(400);
+        return { error: 'Workspace name must be 100 characters or fewer' };
+      }
+      if (!folderPath || typeof folderPath !== 'string' || folderPath.trim().length === 0) {
+        reply.status(400);
+        return { error: 'Workspace path is required' };
+      }
+      const resolvedPath = path.resolve(folderPath.trim()); // Resolved absolute target path.
+      if (!fs.existsSync(resolvedPath)) {
+        reply.status(400);
+        return { error: 'Workspace path does not exist' };
+      }
+      if (!fs.statSync(resolvedPath).isDirectory()) {
+        reply.status(400);
+        return { error: 'Workspace path must be a directory' };
+      }
+      try {
+        fs.accessSync(resolvedPath, fs.constants.R_OK);
+      } catch {
+        reply.status(400);
+        return { error: 'Workspace path is not readable' };
+      }
+      const createdWs = db.createWorkspace(name.trim(), resolvedPath); // Reference to the created workspace.
+      return createdWs;
+    }
+  );
+
+  server.delete<{ Params: { id: string } }>('/api/workspaces/:id', async (request, reply) => {
+    const id = request.params.id; // Target workspace ID.
+    console.log(`[API] DELETE /api/workspaces/${id} -> deleting workspace`);
+    const wsList = db.getWorkspaces(); // Entire registered workspaces array.
+    const targetWs = wsList.find(w => w.id === id); // Found workspace object matching the target ID.
+    if (targetWs) {
+      console.log(`[API] Deleting workspace "${targetWs.name}" (id=${id}) with ${targetWs.tabs.length} tabs`);
+      await Promise.all(
+        targetWs.tabs.map(async tab => {
+          console.log(`[API] Cleaning up tab ${tab.id} for workspace delete`);
+          await pty.killPtySession(tab.id);
+          if (tab.worktreePath) {
+            try {
+              await git.removeGitWorktree(targetWs.path, tab.worktreePath);
+            } catch (err) {
+              // Ignore pruning issues.
+            }
+          }
+        })
+      ); // Run PTY shutdowns and worktree cleanups concurrently.
+      db.deleteWorkspace(id);
+      console.log(`[API] Workspace ${id} deleted`);
+    }
+    const successResp = { success: true }; // Server confirmation object.
+    return successResp;
+  });
+
+  server.put<{ Params: { id: string }; Body: Partial<Omit<db.Workspace, 'id' | 'tabs'>> }>(
+    '/api/workspaces/:id',
+    async (request, reply) => {
+      const id = request.params.id; // Target workspace ID.
+      const updates = request.body; // Updated attributes from body.
+      const updated = db.updateWorkspace(id, updates); // Workspace with applied patches.
+      const returnResult = updated; // Refactored return workspace.
+      return returnResult;
+    }
+  );
+
+  const MAX_TABS_PER_WORKSPACE = 4; // Maximum number of terminal tabs allowed per workspace.
+
+  server.post<{ Params: { id: string }; Body: { name: string; shell?: string } }>(
+    '/api/workspaces/:id/tabs',
+    async (request, reply) => {
+      const id = request.params.id; // Parent workspace ID.
+      const { name, shell } = request.body; // Input body variables.
+      console.log(`[API] POST /api/workspaces/${id}/tabs -> creating tab name="${name}" shell="${shell}"`);
+      const targetWs = db.getWorkspaces().find(w => w.id === id); // Find matching workspace database entry.
+      if (!targetWs) {
+        reply.status(404);
+        const errorResp = { error: 'Workspace not found' }; // Missing workspace error.
+        return errorResp;
+      }
+      if (targetWs.tabs.length >= MAX_TABS_PER_WORKSPACE) {
+        reply.status(400);
+        const errorResp = { error: `Maximum ${MAX_TABS_PER_WORKSPACE} terminal tabs per workspace` }; // Tab limit error.
+        return errorResp;
+      }
+      const tab = db.createTerminalTab(id, name, targetWs.path, shell); // New tab object created.
+      if (tab) {
+        console.log(`[API] Tab created: id=${tab.id} name="${name}" cwd=${tab.cwd}`);
+      }
+      const returnResult = tab; // Created tab descriptor.
+      return returnResult;
+    }
+  );
+
+  server.put<{ Params: { id: string; tabId: string }; Body: { name?: string; branch?: string } }>(
+    '/api/workspaces/:id/tabs/:tabId',
+    async (request, reply) => {
+      const { id, tabId } = request.params; // Workspace and tab parameter keys.
+      const { name, branch } = request.body; // Extracted updates.
+      console.log(`[API] PUT /api/workspaces/${id}/tabs/${tabId} -> name="${name}" branch="${branch}"`);
+      const targetWs = db.getWorkspaces().find(w => w.id === id); // Target workspace object.
+      if (!targetWs) {
+        reply.status(404);
+        const errorResp = { error: 'Workspace not found' }; // Error payload.
+        return errorResp;
+      }
+      const tab = targetWs.tabs.find(t => t.id === tabId); // Selected terminal tab.
+      if (!tab) {
+        reply.status(404);
+        const errorResp = { error: 'Terminal tab not found' }; // Error payload.
+        return errorResp;
+      }
+
+      let worktreePath = tab.worktreePath; // Preserve current worktree path reference.
+      let newCwd = tab.cwd; // Preserve current target current working directory.
+
+      if (branch !== undefined && branch !== tab.branch) {
+        console.log(`[API] Branch change detected for tab ${tabId}: "${tab.branch}" -> "${branch}", killing PTY`);
+        await pty.killPtySession(tabId);
+        if (tab.worktreePath) {
+          try {
+            await git.removeGitWorktree(targetWs.path, tab.worktreePath);
+          } catch (err) {
+            // Prune error.
+          }
+          worktreePath = undefined;
+          newCwd = targetWs.path;
+        }
+        if (branch && branch.trim().length > 0) {
+          try {
+            const wPath = await git.setupGitWorktree(targetWs.path, branch); // Spawn isolated git worktree folder.
+            worktreePath = wPath;
+            newCwd = wPath;
+          } catch (err: any) {
+            reply.status(400);
+            const errorResp = { error: err.message || 'Failed to setup git worktree' }; // Setup error.
+            return errorResp;
+          }
+        } else {
+          newCwd = targetWs.path;
+        }
+      }
+
+      const updates: Partial<db.TerminalTab> = {}; // Config updates map.
+      if (name !== undefined) {
+        updates.name = name;
+      }
+      if (branch !== undefined) {
+        updates.branch = branch ? branch : undefined;
+        updates.worktreePath = worktreePath;
+        updates.cwd = newCwd;
+      }
+
+      const updated = db.updateTerminalTab(id, tabId, updates); // Flush updates to sessions database.
+      const returnResult = updated; // Updated tab object.
+      return returnResult;
+    }
+  );
+
+  server.post<{ Params: { id: string; tabId: string }; Body: { name: string } }>(
+    '/api/workspaces/:id/tabs/:tabId/branches',
+    async (request, reply) => {
+      const { id, tabId } = request.params; // Workspace and tab keys.
+      const { name: branchName } = request.body; // New branch name.
+      console.log(`[API] POST /api/workspaces/${id}/tabs/${tabId}/branches -> branch="${branchName}"`);
+      const targetWs = db.getWorkspaces().find(w => w.id === id); // Found workspace.
+      if (!targetWs) {
+        reply.status(404);
+        const errorResp = { error: 'Workspace not found' }; // Error payload.
+        return errorResp;
+      }
+      const tab = targetWs.tabs.find(t => t.id === tabId); // Target tab config.
+      if (!tab) {
+        reply.status(404);
+        const errorResp = { error: 'Terminal tab not found' }; // Error.
+        return errorResp;
+      }
+      try {
+        await git.createBranch(targetWs.path, branchName);
+        await pty.killPtySession(tabId);
+        if (tab.worktreePath) {
+          try {
+            await git.removeGitWorktree(targetWs.path, tab.worktreePath);
+          } catch (err) {
+            // Prune error.
+          }
+        }
+        const wPath = await git.setupGitWorktree(targetWs.path, branchName); // Create new worktree directly.
+        const updated = db.updateTerminalTab(id, tabId, {
+          branch: branchName,
+          worktreePath: wPath,
+          cwd: wPath,
+        }); // Apply updates to database tab.
+        const returnResult = updated; // Tab payload.
+        return returnResult;
+      } catch (err: any) {
+        reply.status(400);
+        const errorResp = { error: err.message || 'Failed to create git branch' }; // Error payload.
+        return errorResp;
+      }
+    }
+  );
+
+  server.delete<{ Params: { id: string; tabId: string } }>(
+    '/api/workspaces/:id/tabs/:tabId',
+    async (request, reply) => {
+      const { id, tabId } = request.params; // Tab and workspace parameters.
+      console.log(`[API] DELETE /api/workspaces/${id}/tabs/${tabId} -> deleting tab`);
+      const targetWs = db.getWorkspaces().find(w => w.id === id); // Found workspace.
+      if (targetWs) {
+        const tab = targetWs.tabs.find(t => t.id === tabId); // Target tab config.
+        console.log(`[API] Killing PTY and cleaning up worktree for tab ${tabId}`);
+        await pty.killPtySession(tabId);
+        if (tab && tab.worktreePath) {
+          try {
+            await git.removeGitWorktree(targetWs.path, tab.worktreePath);
+          } catch (err) {
+            // Ignore.
+          }
+        }
+        db.deleteTerminalTab(id, tabId);
+        console.log(`[API] Tab ${tabId} deleted`);
+      }
+      const successResp = { success: true }; // Operation complete.
+      return successResp;
+    }
+  );
+
+  server.get<{ Params: { id: string } }>('/api/workspaces/:id/git/branches', async (request, reply) => {
+    const id = request.params.id; // Target workspace ID.
+    const ws = db.getWorkspaces().find(w => w.id === id); // Target workspace instance.
+    if (!ws) {
+      reply.status(404);
+      const errorResp = { error: 'Workspace not found' }; // Error workspace message.
+      return errorResp;
+    }
+    try {
+      const branches = await git.getBranches(ws.path); // Retrieve active branch array from workspace folder.
+      const returnResult = branches; // Branches array result.
+      return returnResult;
+    } catch (err: any) {
+      reply.status(500);
+      const errorResp = { error: err.message || 'Failed to query git branches' }; // Error payload.
+      return errorResp;
+    }
+  });
+
+  server.get<{ Querystring: { name: string } }>('/api/branches/in-use', async (request, reply) => {
+    const { name } = request.query; // Branch name to check.
+    const allWorkspaces = db.getWorkspaces(); // All registered workspaces.
+    let inUse = false; // Default safety flag.
+    for (const ws of allWorkspaces) {
+      for (const tab of ws.tabs) {
+        if (tab.branch === name) {
+          inUse = true;
+          break;
+        }
+      }
+      if (inUse) { break; }
+    }
+    const result = { inUse }; // Response payload.
+    return result;
+  });
+
+  // Returns the current Tailscale status and connection info for the server.
+  server.get('/api/tailscale/status', async (request, reply) => {
+    const installed = tailscale.isTailscaleInstalled(); // Whether the tailscale binary exists on PATH.
+    const info = installed ? tailscale.getTailscaleInfo() : null; // Parsed tailscale status, null if not connected.
+    return {
+      installed,
+      connected: info !== null,
+      tailscale: info,
+      tailscaleMode: TAILSCALE_MODE,
+    };
+  });
+
+  server.get('/api/browse', async (request, reply) => {
+    try {
+      const folder = await git.showFolderPicker();
+      if (!folder) {
+        // User cancelled the dialog — not an error.
+        return { path: '', cancelled: true };
+      }
+      return { path: folder };
+    } catch (err: any) {
+      reply.status(500);
+      return { path: '', error: err.message || 'Failed to open folder picker' };
+    }
+  });
+
+  server.route({
+    method: 'GET',
+    url: '/ws/observer',
+    handler: (request, reply) => {
+      reply.status(400).send('WebSocket connection expected');
+    },
+    wsHandler: (connection, req) => {
+      observerSockets.add(connection);
+      const initialPayload = JSON.stringify({
+        type: 'observer',
+        sessions: pty.getAllSessions(),
+      }); // Initial data load payload for new client.
+      connection.send(initialPayload);
+      connection.on('close', () => {
+        observerSockets.delete(connection);
+      });
+    },
+  });
+
+  server.route({
+    method: 'GET',
+    url: '/ws/terminal/:tabId',
+    handler: (request, reply) => {
+      reply.status(400).send('WebSocket connection expected');
+    },
+    wsHandler: async (connection, req) => {
+      const tabId = (req.params as any).tabId; // Extract tabId from parameters.
+      console.log(`[WS] Terminal WebSocket connect: tabId=${tabId}`);
+      const workspaces = db.getWorkspaces(); // Load workspaces registry.
+      let activeTab: db.TerminalTab | undefined = undefined; // Matches the target active tab.
+      let activeWs: db.Workspace | undefined = undefined; // Matches the parent workspace containing the tab.
+      for (const ws of workspaces) {
+        const found = ws.tabs.find(t => t.id === tabId); // Match lookup.
+        if (found) {
+          activeTab = found;
+          activeWs = ws;
+          break;
+        }
+      }
+      if (!activeTab || !activeWs) {
+        console.log(`[WS] Terminal tab ${tabId} not found in any workspace, closing connection`);
+        connection.close(4001, 'Terminal tab not found');
+        return;
+      }
+      console.log(`[WS] Calling getOrCreatePtySession for tab ${tabId} (workspace=${activeWs.name}, cwd=${activeTab.cwd})`);
+      let session: pty.TerminalSession; // Reference to the created or retrieved terminal session.
+      try {
+        session = await pty.getOrCreatePtySession(
+          activeWs.id,
+          activeTab.id,
+          activeTab.cwd,
+          activeTab.shell,
+          broadcastObserverUpdate
+        ); // Await spawn or attach of persistent session process (serialized on Windows).
+      } catch (err: any) {
+        console.log(`[WS] getOrCreatePtySession failed for tab ${tabId}: ${err.message}`);
+        connection.close(4002, 'Terminal session creation failed');
+        return;
+      }
+      console.log(`[WS] getOrCreatePtySession returned for tab ${tabId}, PID=${session.ptyProcess.pid}`);
+
+      session.activeSocket = connection; // Register the newly connected socket as the active connection.
+
+      session.outputBuffer.forEach(chunk => {
+        connection.send(chunk);
+      });
+
+      // Handles incoming data from the persistent PTY process by sending it over the WebSocket.
+      session.onData = (data: string) => {
+        try {
+          if (session.activeSocket === connection) {
+            connection.send(data);
+          }
+        } catch (err) {
+          // Socket write failed.
+        }
+      };
+
+      // Receives input and resize instructions from the WebSocket and forwards them to the PTY session.
+      connection.on('message', (messageData: any) => {
+        const rawMessage = messageData.toString(); // Normalized string representation of the incoming socket message.
+        try {
+          const parsed = JSON.parse(rawMessage); // Parsed client websocket message.
+          if (parsed && parsed.type === 'resize') {
+            pty.resizePtySession(tabId, parsed.cols, parsed.rows);
+          } else if (parsed && parsed.type === 'input') {
+            pty.writeToPtySession(tabId, parsed.data);
+          }
+        } catch (err) {
+          // Ignore invalid JSON payloads to prevent writing garbage or raw JSON controls to the shell.
+        }
+      });
+
+      // Disconnects the WebSocket connection and marks the PTY session active socket as empty.
+      connection.on('close', () => {
+        console.log(`[WS] Terminal WebSocket disconnect: tabId=${tabId}`);
+        if (session.activeSocket === connection) {
+          session.activeSocket = undefined;
+          session.onData = () => {};
+        }
+      });
+    },
+  });
+
+  const listenHost = resolveListenHost(); // Network interface to bind the server to.
+  await server.listen({ port: PORT, host: listenHost });
+  const tailscaleInfo = TAILSCALE_MODE ? tailscale.getTailscaleInfo() : null; // Information about the current Tailscale connection.
+  if (tailscaleInfo) {
+    console.log(`Tailscale URL: http://${tailscaleInfo.ip}:${PORT}`);
+    if (tailscaleInfo.dnsName) {
+      console.log(`Tailscale DNS: https://${tailscaleInfo.dnsName}:${PORT}`);
+    }
+  }
+  console.log(`Backend daemon is listening on port ${PORT} (bound to ${listenHost})`);
+}
+
+bootstrap().catch(err => {
+  console.error('Fatal initialization error:', err);
+  process.exit(1);
+});