@profoundlogic/coderflow-server 0.4.4 → 0.4.6

package/dist/start.js.bak

@@ -0,0 +1,1381 @@
+#!/usr/bin/env node
+/**
+ * CoderFlow Server
+ * Main entry point - sets up Express server and routes
+ */
+
+import http from 'http';
+import https from 'https';
+import express from 'express';
+import compression from 'compression';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Load environment variables from .env file
+// Priority: 1) coder-setup/.env  2) package/.env
+import dotenv from 'dotenv';
+import { existsSync } from 'fs';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Check for .env in coder-setup directory first
+const coderSetupPath = process.env.CODER_SETUP_PATH;
+const setupEnvPath = coderSetupPath ? path.join(coderSetupPath, '.env') : null;
+const packageEnvPath = path.join(__dirname, '.env');
+
+let envSource = 'none';
+if (setupEnvPath && existsSync(setupEnvPath)) {
+  dotenv.config({ path: setupEnvPath });
+  envSource = setupEnvPath;
+} else if (existsSync(packageEnvPath)) {
+  dotenv.config({ path: packageEnvPath });
+  envSource = packageEnvPath;
+}
+// Log env source after logger is available (see below)
+import { promises as fs, readFileSync } from 'fs';
+import { WebSocketServer, WebSocket } from 'ws';
+import Docker from 'dockerode';
+import session from 'express-session';
+import MemoryStore from 'memorystore';
+import tasksRouter, { tasks, taskGroups, loadExistingTasks, loadExistingGroups, processAutoJudgeGroupsOnStartup, getTaskDirectories, getBaseTaskStoragePath, codeServerPorts, appServerStates, updateClients, broadcastTaskUpdate } from './routes/tasks.js';
+import containersRouter, { containers } from './routes/containers.js';
+import healthRouter from './routes/health.js';
+import environmentsRouter from './routes/environments.js';
+import templatesRouter from './routes/templates.js';
+import authRouter from './routes/auth.js';
+import passwordRouter from './routes/password.js';
+import usersRouter from './routes/users.js';
+import apiKeysRouter from './routes/apiKeys.js';
+import jiraRouter, { initializeJira } from './routes/jira.js';
+import testRouter from './routes/test.js';
+import testTaskRouter from './routes/test-task.js';
+import deployTaskRouter from './routes/deploy-task.js';
+import promptRouter from './routes/prompt.js';
+import visualizationsRouter from './routes/visualizations.js';
+import settingsRouter, { initializeSetupPath } from './routes/settings.js';
+import gitProviderSetupRouter from './routes/git-provider-setup.js';
+import { initializeEmailConfigPath } from './lib/email.js';
+import providerAuthRouter from './routes/provider-auth.js';
+import qaRouter from './routes/qa.js';
+import buildRouter from './routes/build.js';
+import skillsRouter from './routes/skills.js';
+import externalSkillsRouter from './routes/external-skills.js';
+import gitCredentialsRouter, { initializeSetupPath as initializeGitCredentialsPath } from './routes/git-credentials.js';
+import objectiveManagementRouter, { initializeObjectiveManagement } from './routes/objective-management.js';
+import environmentManagementRouter, { initializeEnvironmentManagement, updateCoderConfig as updateEnvironmentManagementConfig } from './routes/environment-management.js';
+import skillManagementRouter, { initializeSkillManagement, updateSkillManagementConfig } from './routes/skill-management.js';
+import authOidcRouter from './routes/auth-oidc.js';
+import gitOAuthRouter from './routes/git-oauth.js';
+import teamsRouter from './routes/teams.js';
+import bindingsRouter from './routes/bindings.js';
+import rolesRouter from './routes/roles.js';
+import { loadOidcConfig } from './lib/oidc-auth.js';
+import { migrateConfigFiles } from './lib/config-migration.js';
+import { requireAuth, requireAdmin } from './middleware/requireAuth.js';
+import { requireInit, setCoderConfig } from './middleware/requireInit.js';
+import { loadCoderSetup } from './config.js';
+import { loadRoles } from './lib/role-definitions.js';
+import { getUsers } from './lib/users.js';
+import { validateLicense } from './lib/entitlement.js';
+import { logger } from './lib/logger.js';
+import { createAgentKeepAliveService } from './lib/agent-keepalive.js';
+import { createBuildSchedulerService } from './lib/build-scheduler.js';
+import { DATA_DIR, getSessionSecret } from './lib/data-dir.js';
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+const HOST = process.env.HOST || '0.0.0.0';
+const CODER_SETUP_PATH = process.env.CODER_SETUP_PATH;
+
+// Trust proxy when behind a reverse proxy (nginx, Apache, load balancer, etc.)
+// This ensures req.secure, req.protocol, req.hostname work correctly
+if (process.env.TRUST_PROXY) {
+  app.set('trust proxy', process.env.TRUST_PROXY === 'true' ? true : process.env.TRUST_PROXY);
+  logger.info('Trust proxy enabled', { trustProxy: app.get('trust proxy') });
+}
+
+// Log if using custom data directory
+if (process.env.SERVER_DATA_PATH) {
+  logger.info('Using server data path override from environment', { dataDir: DATA_DIR });
+}
+
+// SSL/TLS Configuration (optional)
+const SSL_CERT_PATH = process.env.SSL_CERT_PATH; // Path to certificate file (.crt or .pem)
+const SSL_KEY_PATH = process.env.SSL_KEY_PATH;   // Path to private key file (.key or .pem)
+const SSL_CA_PATH = process.env.SSL_CA_PATH;     // Optional: Path to CA bundle
+
+const docker = new Docker();
+
+// Global config storage
+export let coderConfig = null;
+export let setupPath = null;
+
+/**
+ * Reload coder-setup configuration from disk
+ * Used after environment modifications (create, delete, etc.)
+ * Also reloads dependent services (build-scheduler, agent-keepalive, jira)
+ */
+export async function reloadCoderConfig() {
+  if (!setupPath) {
+    throw new Error('No setup path configured');
+  }
+
+  logger.info('Starting configuration reload...');
+
+  const { loadCoderSetup } = await import('./config.js');
+  const newConfig = await loadCoderSetup(setupPath);
+
+  // Re-add host repos path
+  newConfig.hostReposPath = path.resolve(__dirname, '..', '..', '..');
+
+  logger.info('Configuration loaded from disk', {
+    environments: Object.keys(newConfig.environments).join(', ')
+  });
+
+  // Update global reference FIRST (so routes see new config immediately)
+  coderConfig = newConfig;
+
+  // Reload dependent services
+  const reloadErrors = [];
+
+  try {
+    // Reload JIRA client
+    const { reloadJiraClient } = await import('./routes/jira.js');
+    await reloadJiraClient(newConfig);
+  } catch (error) {
+    logger.error('Failed to reload JIRA client', { error: error.message });
+    reloadErrors.push('JIRA client');
+  }
+
+  try {
+    // Reload build scheduler
+    const { buildSchedulerService } = global.services || {};
+    if (buildSchedulerService) {
+      await buildSchedulerService.reload(newConfig);
+    }
+  } catch (error) {
+    logger.error('Failed to reload build scheduler', { error: error.message });
+    reloadErrors.push('Build scheduler');
+  }
+
+  try {
+    // Reload agent keep-alive
+    const { agentKeepAliveService } = global.services || {};
+    if (agentKeepAliveService) {
+      await agentKeepAliveService.reload(newConfig);
+    }
+  } catch (error) {
+    logger.error('Failed to reload agent keep-alive', { error: error.message });
+    reloadErrors.push('Agent keep-alive');
+  }
+
+  // Update task-based management routes with new config
+  try {
+    updateEnvironmentManagementConfig(newConfig);
+    updateSkillManagementConfig(newConfig);
+  } catch (error) {
+    logger.error('Failed to update task management routes config', { error: error.message });
+    reloadErrors.push('Task management routes');
+  }
+
+  if (reloadErrors.length > 0) {
+    logger.warn('Configuration reloaded with errors', {
+      failedServices: reloadErrors.join(', ')
+    });
+  } else {
+    logger.info('Configuration and all services reloaded successfully');
+  }
+
+  return coderConfig;
+}
+
+// Middleware
+
+// Enable gzip/deflate compression for all responses
+// This significantly reduces payload sizes over the network (typically 70-80% reduction)
+app.use(compression({
+  // Compress responses above 1KB
+  threshold: 1024,
+  // Use maximum compression level for best size reduction
+  level: 6,
+  // Filter function to decide what to compress
+  filter: (req, res) => {
+    // Never compress SSE responses - compression buffers break streaming updates
+    const ssePaths = [
+      /^\/tasks\/updates/,
+      /^\/tasks\/[^/]+\/stream/,
+      /^\/tasks\/[^/]+\/tests\/[^/]+\/stream\//,
+      /^\/tasks\/[^/]+\/exec-stream/,
+      /^\/prompt\/stream/
+    ];
+    const acceptsEventStream = (req.headers.accept || '').includes('text/event-stream');
+    if (acceptsEventStream || ssePaths.some(pattern => pattern.test(req.path))) {
+      return false;
+    }
+
+    // Don't compress if client doesn't accept it
+    if (req.headers['x-no-compression']) {
+      return false;
+    }
+    // Use compression's default filter (compresses text-based content types)
+    return compression.filter(req, res);
+  }
+}));
+
+// Skip body parsing for proxy routes to allow http-proxy to forward the raw body
+app.use((req, res, next) => {
+  // Skip JSON parsing for app server proxy routes and vscode proxy routes
+  if (req.path.match(/^\/tasks\/[^/]+\/(app\/\d+|vscode)/)) {
+    return next();
+  }
+  express.json({ limit: '10mb' })(req, res, next);
+});
+
+// Session middleware - using in-memory store with persistence on shutdown
+const SessionStore = MemoryStore(session);
+const SESSION_BACKUP_PATH = path.join(DATA_DIR, 'sessions-backup.json');
+const SESSION_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days in milliseconds
+
+// Create the session store instance (exported for shutdown persistence)
+const sessionStore = new SessionStore({
+  checkPeriod: 86400000, // Prune expired entries every 24h
+  ttl: SESSION_TTL
+});
+
+// Restore sessions from backup file SYNCHRONOUSLY at startup
+// This must happen before the session middleware processes any requests
+function restoreSessionsSync() {
+  try {
+    const data = readFileSync(SESSION_BACKUP_PATH, 'utf8');
+    const backup = JSON.parse(data);
+    const now = Date.now();
+    let restored = 0;
+    let expired = 0;
+
+    for (const [sid, sessionData] of Object.entries(backup.sessions || {})) {
+      // Check if session is still valid (not expired)
+      const cookie = sessionData.cookie;
+      if (cookie && cookie.expires) {
+        const expiresAt = new Date(cookie.expires).getTime();
+        if (expiresAt > now) {
+          sessionStore.set(sid, sessionData, () => {});
+          restored++;
+        } else {
+          expired++;
+        }
+      }
+    }
+
+    logger.info('Sessions restored from backup', { restored, expired, backupTime: backup.savedAt });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      logger.info('No session backup file found, starting fresh');
+    } else {
+      logger.warn('Failed to restore sessions from backup', { error: error.message });
+    }
+  }
+}
+
+// Restore sessions immediately during module initialization
+restoreSessionsSync();
+
+// Save sessions to backup file (called on shutdown)
+async function saveSessions() {
+  return new Promise((resolve) => {
+    sessionStore.all((err, sessions) => {
+      if (err) {
+        logger.error('Failed to get sessions for backup', { error: err.message });
+        resolve();
+        return;
+      }
+
+      const backup = {
+        savedAt: new Date().toISOString(),
+        sessions: sessions || {}
+      };
+
+      fs.writeFile(SESSION_BACKUP_PATH, JSON.stringify(backup, null, 2))
+        .then(() => {
+          const count = Object.keys(backup.sessions).length;
+          logger.info('Sessions saved to backup', { count });
+          resolve();
+        })
+        .catch((writeErr) => {
+          logger.error('Failed to write session backup', { error: writeErr.message });
+          resolve();
+        });
+    });
+  });
+}
+
+// Export for shutdown handler
+export { saveSessions };
+
+// Determine if we're using HTTPS directly (via SSL cert/key config)
+const hasDirectSSL = !!(SSL_CERT_PATH && SSL_KEY_PATH);
+
+// When behind a trusted proxy, use 'auto' so express-session checks req.secure per-request.
+// This allows secure cookies for proxied HTTPS while still working over plain HTTP
+// (e.g., Playwright tests hitting localhost directly inside the container).
+// With direct SSL (no proxy), always set secure: true.
+const secureCookie = hasDirectSSL ? true : (app.get('trust proxy') ? 'auto' : false);
+
+// SameSite setting: 'none' allows cookies to work in proxied contexts (Testing menu)
+// but requires secure flag. Use 'lax' for local dev / direct HTTP.
+// When secureCookie is 'auto', sameSite must also adapt: use 'lax' as the safe default
+// and let the proxy's X-Forwarded-Proto drive the secure flag per-request.
+const sameSite = hasDirectSSL ? 'none' : 'lax';
+
+// Get session secret (shared between host and container via data directory)
+const sessionSecret = getSessionSecret();
+
+// Log environment configuration source
+if (envSource !== 'none') {
+  logger.info('Environment configuration loaded', { path: envSource });
+}
+
+logger.info('Session configuration', {
+  secretSource: process.env.SESSION_SECRET ? 'environment' : 'shared file',
+  secure: secureCookie,
+  sameSite,
+  trustProxy: !!app.get('trust proxy'),
+  store: 'in-memory with persistence',
+  dataDir: DATA_DIR
+});
+
+app.use(session({
+  store: sessionStore,
+  secret: sessionSecret,
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    maxAge: SESSION_TTL,
+    httpOnly: true,
+    secure: secureCookie,
+    sameSite: sameSite
+  },
+  name: `coder.${PORT}.sid` // Custom session ID cookie name (port-specific to avoid collisions)
+}));
+
+// API Routes (defined first so they take precedence)
+// Auth routes (public)
+app.use('/auth', authRouter);
+
+// OIDC auth routes (public)
+app.use('/auth/oidc', authOidcRouter);
+
+// Password routes (public for token validation and setup, admin for token creation)
+app.use('/password', passwordRouter);
+
+// Protected API routes (require authentication and valid init)
+app.use('/tasks', requireAuth, requireInit, tasksRouter);
+app.use('/containers', requireAuth, containersRouter);
+app.use('/environments', requireAuth, environmentsRouter);
+app.use('/templates', requireAuth, templatesRouter);
+app.use('/api-keys', requireAuth, apiKeysRouter);
+app.use('/jira', requireAuth, jiraRouter);
+app.use('/test', requireAuth, testRouter);
+app.use('/test-task', requireAuth, testTaskRouter);
+app.use('/deploy-task', requireAuth, deployTaskRouter);
+app.use('/prompt-parameter', requireAuth, promptRouter);
+app.use('/visualizations', requireAuth, visualizationsRouter);
+app.use('/qa', requireAuth, qaRouter);
+app.use('/build', requireAuth, buildRouter);
+app.use('/skills', requireAuth, skillsRouter);
+app.use('/external-skills', requireAuth, externalSkillsRouter);
+
+// Admin-only routes
+app.use('/users', requireAuth, requireAdmin, usersRouter);
+app.use('/settings', requireAuth, settingsRouter);
+app.use('/settings/provider-auth', requireAuth, providerAuthRouter);
+app.use('/settings/git-provider-setup', requireAuth, gitProviderSetupRouter);
+
+// Scoped RBAC routes (teams, bindings, roles handle their own authorization per-endpoint)
+app.use('/teams', requireAuth, teamsRouter);
+app.use('/bindings', requireAuth, bindingsRouter);
+app.use('/roles', requireAuth, rolesRouter);
+
+// Health check (public for monitoring)
+app.use('/health', healthRouter);
+
+// Git credentials endpoint (uses container token auth, not session auth)
+app.use('/api/git/credentials', gitCredentialsRouter);
+
+// Git OAuth endpoint (user-level OAuth for Git providers)
+app.use('/api/git-oauth', requireAuth, gitOAuthRouter);
+
+// Objective management endpoint (uses task ID auth for container access)
+// Allows tasks launched from objectives to manage their parent objective
+app.use('/api/objective-management', objectiveManagementRouter);
+
+// Environment management endpoint (uses task ID auth for container access)
+// Allows tasks to update environment instructions (AGENTS.md) and templates
+app.use('/api/environment-management', environmentManagementRouter);
+
+// Skill management endpoint (uses task ID auth for container access)
+// Allows tasks to edit skills assigned to their environment
+app.use('/api/skill-management', skillManagementRouter);
+
+// Serve user avatars (requires auth - checking is done at upload time)
+const avatarsPath = path.join(DATA_DIR, 'avatars');
+app.use('/avatars', express.static(avatarsPath, {
+  setHeaders: (res) => {
+    res.setHeader('Cache-Control', 'public, max-age=86400'); // 1 day cache
+  }
+}));
+
+// Serve documentation (public, no auth)
+// Check both possible locations: dist/web-ui (installed) and ../web-ui (source)
+const docsPathDist = path.join(__dirname, 'web-ui/public/docs');
+const docsPathSource = path.join(__dirname, '../web-ui/public/docs');
+const docsPath = existsSync(docsPathDist) ? docsPathDist : docsPathSource;
+app.use('/docs', express.static(docsPath, {
+  setHeaders: (res, filePath) => {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.html') {
+      res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+    } else if (ext === '.md') {
+      res.setHeader('Cache-Control', 'public, max-age=300'); // 5 min cache for markdown
+    }
+  }
+}));
+
+// Serve internal dev docs (only when running from source, not from npm package)
+const devDocsPath = path.join(__dirname, '../../docs');
+if (existsSync(devDocsPath)) {
+  app.use('/dev-docs', express.static(devDocsPath, {
+    setHeaders: (res, filePath) => {
+      const ext = path.extname(filePath).toLowerCase();
+      if (ext === '.html') {
+        res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+      } else if (ext === '.md') {
+        res.setHeader('Cache-Control', 'no-cache'); // No cache for dev docs
+      }
+    }
+  }));
+}
+
+// Serve Web UI static files with caching headers
+// Static assets (JS, CSS, images) are cached for 1 day to reduce repeat requests
+// HTML files are not cached to ensure users always get the latest version
+// Check both possible locations: dist/web-ui (installed) and ../web-ui (source)
+const webUiPathDist = path.join(__dirname, 'web-ui/public');
+const webUiPathSource = path.join(__dirname, '../web-ui/public');
+const webUiPath = existsSync(webUiPathDist) ? webUiPathDist : webUiPathSource;
+app.use(express.static(webUiPath, {
+  // Set cache headers for static assets
+  setHeaders: (res, filePath) => {
+    const ext = path.extname(filePath).toLowerCase();
+
+    // Cache JS, CSS, and image files for 1 day (these have version query strings)
+    if (['.js', '.css', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.woff', '.woff2', '.ttf'].includes(ext)) {
+      res.setHeader('Cache-Control', 'public, max-age=86400'); // 1 day
+    } else if (ext === '.html') {
+      // Don't cache HTML files - always fetch fresh
+      res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+      res.setHeader('Pragma', 'no-cache');
+      res.setHeader('Expires', '0');
+    }
+  },
+  // Enable etag for cache validation
+  etag: true,
+  // Enable Last-Modified header
+  lastModified: true
+}));
+logger.info('Web UI enabled', { path: webUiPath, caching: 'enabled for static assets' });
+
+// Referer-based redirect fallback for Vite/ES module imports
+// When a module loaded from /tasks/{id}/app/{port}/... imports another module via
+// an absolute path like "/foo.js", the browser requests "/foo.js" directly (no prefix).
+// This middleware catches such requests, extracts taskId/port from the Referer header,
+// and 302 redirects to the prefixed URL. The redirect (not proxy) is critical: it ensures
+// the browser loads the module from the prefixed URL, so its own imports carry the correct
+// Referer, maintaining the chain at any depth.
+app.use((req, res, next) => {
+  // Only handle GET requests that haven't matched any route
+  if (req.method !== 'GET') return next();
+
+  // Don't redirect requests that are already prefixed or to known paths
+  if (req.path.startsWith('/tasks/') || req.path.startsWith('/api/') ||
+      req.path.startsWith('/auth/') || req.path.startsWith('/dev-docs/')) {
+    return next();
+  }
+
+  const referer = req.headers.referer || req.headers.referrer;
+  if (!referer) return next();
+
+  // Extract taskId and port from Referer
+  const refMatch = referer.match(/\/tasks\/([^\/]+)\/app\/(\d+)/);
+  if (!refMatch) return next();
+
+  const taskId = refMatch[1];
+  const port = refMatch[2];
+
+  // Verify task is active
+  const state = appServerStates.get(taskId);
+  if (!state || !state.proxies) return next();
+
+  // Verify this port belongs to the task
+  let portValid = false;
+  if (state.ports) {
+    for (const [, portInfo] of state.ports.entries()) {
+      if (portInfo.internal.toString() === port) {
+        portValid = true;
+        break;
+      }
+    }
+  } else if (state.isProxyMode) {
+    portValid = true;
+  }
+  if (!portValid) return next();
+
+  const redirectUrl = `/tasks/${taskId}/app/${port}${req.originalUrl}`;
+  logger.debug('Referer-based redirect for ES module import', {
+    taskId,
+    port,
+    from: req.originalUrl,
+    to: redirectUrl
+  });
+  res.redirect(302, redirectUrl);
+});
+
+// Error handling middleware (must be after all routes)
+app.use((err, req, res, next) => {
+  // Handle PayloadTooLargeError specifically
+  if (err.type === 'entity.too.large' || err.status === 413) {
+    logger.error('Payload too large', {
+      url: req.url,
+      method: req.method,
+      error: err.message
+    });
+    return res.status(413).json({
+      error: 'Payload too large',
+      message: 'The request payload is too large. This typically occurs when capturing local state with large diffs. Consider committing or stashing large changes before capturing local state.'
+    });
+  }
+
+  // Log all other errors
+  logger.error('Request error', {
+    url: req.url,
+    method: req.method,
+    error: err.message,
+    stack: err.stack
+  });
+
+  // Send error response
+  const statusCode = err.status || err.statusCode || 500;
+  res.status(statusCode).json({
+    error: err.name || 'Server Error',
+    message: err.message || 'An unexpected error occurred'
+  });
+});
+
+// Load configuration and start server
+async function startServer() {
+  // Load coder-setup configuration if path is provided
+  if (CODER_SETUP_PATH) {
+    try {
+      logger.info('Loading coder-setup', { path: CODER_SETUP_PATH });
+      setupPath = CODER_SETUP_PATH;
+      coderConfig = await loadCoderSetup(CODER_SETUP_PATH);
+
+      // Calculate host repos path (parent directory of profound-coder)
+      // __dirname is at: /path/to/profound-coder/packages/server
+      // We need to go up 3 levels to get to the parent of profound-coder
+      coderConfig.hostReposPath = path.resolve(__dirname, '..', '..', '..');
+
+      logger.info('Configuration loaded successfully', {
+        setupName: coderConfig.setup.name,
+        defaultEnvironment: coderConfig.setup.default_environment,
+        environments: Object.keys(coderConfig.environments).join(', '),
+        hostReposPath: coderConfig.hostReposPath
+      });
+
+      // Initialize settings router with setup path
+      initializeSetupPath({ setupPath: CODER_SETUP_PATH });
+
+      // Migrate instance-specific config files to DATA_DIR
+      await migrateConfigFiles(CODER_SETUP_PATH);
+
+      // Initialize git credentials route with setup path
+      initializeGitCredentialsPath(CODER_SETUP_PATH);
+
+      // Initialize objective management route with tasks map and storage path
+      initializeObjectiveManagement({
+        tasks,
+        taskStoragePath: coderConfig.taskStoragePath,
+        broadcastTaskUpdate
+      });
+
+      // Initialize environment management route with tasks map and setup path
+      initializeEnvironmentManagement({
+        tasks,
+        setupPath: CODER_SETUP_PATH,
+        coderConfig
+      });
+
+      // Initialize skill management route with tasks map and setup path
+      initializeSkillManagement({
+        tasks,
+        setupPath: CODER_SETUP_PATH,
+        coderConfig
+      });
+
+      // Initialize email config path
+      initializeEmailConfigPath(CODER_SETUP_PATH);
+
+      // Set coderConfig reference for license middleware
+      setCoderConfig(coderConfig);
+
+      // Seed predefined roles and check for migration needs
+      await loadRoles();
+
+      // Load OIDC configuration if present
+      try {
+        const oidcConfig = await loadOidcConfig(CODER_SETUP_PATH);
+        if (oidcConfig) {
+          logger.info('OIDC authentication enabled', {
+            displayName: oidcConfig.display_name,
+            issuer: oidcConfig.issuer,
+            autoProvision: oidcConfig.auto_provision,
+            allowLocalAuth: oidcConfig.allow_local_auth
+          });
+        }
+      } catch (oidcError) {
+        logger.error('Failed to load OIDC configuration', oidcError);
+        // Continue without OIDC - it's optional
+      }
+    } catch (error) {
+      logger.error('Failed to load coder-setup', error);
+      process.exit(1);
+    }
+  } else {
+    logger.info('No CODER_SETUP_PATH provided - running in basic mode');
+    logger.info('Set CODER_SETUP_PATH to enable coder-setup integration');
+  }
+
+  // Check that at least one Server Admin exists whenever there are users
+  const allUsers = await getUsers();
+  if (allUsers.length > 0 && !allUsers.some(u => u.isServerAdmin)) {
+    logger.error(
+      '⚠️  NO SERVER ADMIN: Users exist but none has server admin privileges. ' +
+      'The permissions system requires at least one Server Admin. ' +
+      'Please run the migration script: node packages/server/scripts/migrate-to-scoped-rbac.js'
+    );
+  }
+
+  // Validate license
+  const licenseResult = await validateLicense(setupPath);
+  if (!licenseResult.valid) {
+    logger.error('License validation failed', {
+      code: licenseResult.code,
+      message: licenseResult.message
+    });
+    console.error('\n========================================');
+    console.error('LICENSE ERROR');
+    console.error('========================================');
+    console.error(licenseResult.message);
+    console.error('========================================\n');
+    process.exit(1);
+  }
+  logger.info('License validated', {
+    expirationDate: licenseResult.expirationDate
+  });
+
+  // Load existing tasks from disk
+  // Configure task loading via environment variables:
+  // - TASK_LOAD_DAYS: Number of days of tasks to load (default: 365)
+  // - TASK_LOAD_MAX: Maximum number of tasks to load (default: 10000)
+  const taskLoadOptions = {
+    daysToLoad: parseInt(process.env.TASK_LOAD_DAYS) || 365,
+    maxTasks: parseInt(process.env.TASK_LOAD_MAX) || 10000
+  };
+  await loadExistingTasks(taskLoadOptions);
+  await loadExistingGroups();
+  await processAutoJudgeGroupsOnStartup();
+
+  // Initialize JIRA integration if configured
+  await initializeJira();
+
+  // Global service instances (for hot-reload)
+  let buildSchedulerService = null;
+  let agentKeepAliveService = null;
+
+  // Check if we are running inside a task container
+  // If so, we should skip background services that interfere with the host
+  if (process.env.TASK_ID) {
+    logger.info('Running inside a task container - skipping background services', { 
+      taskId: process.env.TASK_ID,
+      skippedServices: ['auto-cleanup', 'agent-keepalive', 'build-scheduler']
+    });
+  } else {
+    // Start auto-cleanup job for inactive containers
+    startAutoCleanup();
+
+    // Start agent keep-alive service (for token refresh)
+    if (coderConfig) {
+      agentKeepAliveService = createAgentKeepAliveService(coderConfig);
+    } else {
+      logger.info('Skipping agent keep-alive - no coder-setup configuration loaded');
+    }
+
+    // Start build scheduler service (for scheduled environment rebuilds)
+    if (coderConfig) {
+      buildSchedulerService = createBuildSchedulerService(coderConfig);
+    } else {
+      logger.info('Skipping build scheduler - no coder-setup configuration loaded');
+    }
+  }
+
+  // Export service instances for hot-reload
+  global.services = { buildSchedulerService, agentKeepAliveService };
+
+  // Create HTTP or HTTPS server based on SSL configuration
+  let server;
+  let protocol = 'http';
+
+  if (SSL_CERT_PATH && SSL_KEY_PATH) {
+    logger.info('SSL configuration detected, creating HTTPS server', {
+      cert: SSL_CERT_PATH,
+      key: SSL_KEY_PATH,
+      ca: SSL_CA_PATH || 'none'
+    });
+
+    // Load SSL certificates
+    const sslOptions = {};
+
+    try {
+      sslOptions.cert = await fs.readFile(SSL_CERT_PATH);
+    } catch (error) {
+      logger.error('Failed to load SSL certificate', { path: SSL_CERT_PATH, error: error.message });
+      console.error('\n========================================');
+      console.error('SSL CERTIFICATE ERROR');
+      console.error('========================================');
+      console.error(`Failed to load SSL certificate: ${SSL_CERT_PATH}`);
+      console.error(`Error: ${error.message}`);
+      console.error('');
+      console.error('Please verify the SSL file paths in your configuration:');
+      console.error('  coder-server config show');
+      console.error('========================================\n');
+      process.exit(1);
+    }
+
+    try {
+      sslOptions.key = await fs.readFile(SSL_KEY_PATH);
+    } catch (error) {
+      logger.error('Failed to load SSL private key', { path: SSL_KEY_PATH, error: error.message });
+      console.error('\n========================================');
+      console.error('SSL PRIVATE KEY ERROR');
+      console.error('========================================');
+      console.error(`Failed to load SSL private key: ${SSL_KEY_PATH}`);
+      console.error(`Error: ${error.message}`);
+      console.error('');
+      console.error('Please verify the SSL file paths in your configuration:');
+      console.error('  coder-server config show');
+      console.error('========================================\n');
+      process.exit(1);
+    }
+
+    // Add CA bundle if provided
+    if (SSL_CA_PATH) {
+      try {
+        sslOptions.ca = await fs.readFile(SSL_CA_PATH);
+      } catch (error) {
+        logger.error('Failed to load SSL CA bundle', { path: SSL_CA_PATH, error: error.message });
+        console.error('\n========================================');
+        console.error('SSL CA BUNDLE ERROR');
+        console.error('========================================');
+        console.error(`Failed to load SSL CA bundle: ${SSL_CA_PATH}`);
+        console.error(`Error: ${error.message}`);
+        console.error('');
+        console.error('Please verify the SSL file paths in your configuration:');
+        console.error('  coder-server config show');
+        console.error('========================================\n');
+        process.exit(1);
+      }
+    }
+
+    server = https.createServer(sslOptions, app);
+    protocol = 'https';
+  } else {
+    server = http.createServer(app);
+  }
+
+  const wss = setupTerminalBridge(server);
+
+  // Track all connections so we can close them during shutdown
+  const connections = new Set();
+  server.on('connection', (socket) => {
+    connections.add(socket);
+    socket.on('close', () => connections.delete(socket));
+  });
+
+  server.listen(PORT, HOST, () => {
+    logger.info('CoderFlow Server listening', {
+      host: HOST,
+      port: PORT,
+      protocol: protocol,
+      environment: process.env.NODE_ENV || 'development'
+    });
+    logger.info('Web UI available at:', {
+      url: `${protocol}://${HOST === '0.0.0.0' ? 'localhost' : HOST}:${PORT}`
+    });
+  });
+
+  // Graceful shutdown handlers for PM2 and other process managers
+  const shutdown = async (signal) => {
+    logger.info(`Received ${signal}, starting graceful shutdown...`);
+
+    // Save sessions to disk before shutting down
+    await saveSessions();
+
+    // Close all SSE client connections
+    const sseClientCount = updateClients.size;
+    if (sseClientCount > 0) {
+      logger.info(`Closing ${sseClientCount} SSE client connections...`);
+      for (const client of updateClients) {
+        try {
+          // Must destroy the socket, not just end() the response
+          // end() only signals we're done writing but keeps the connection open
+          // waiting for the client to close their end, which may never happen
+          if (client.socket && !client.socket.destroyed) {
+            client.socket.destroy();
+          } else {
+            client.end();
+          }
+        } catch (err) {
+          // Ignore errors when closing SSE clients
+        }
+      }
+      updateClients.clear();
+    }
+
+    // Close all WebSocket connections
+    const wsClientCount = wss.clients.size;
+    if (wsClientCount > 0) {
+      logger.info(`Closing ${wsClientCount} WebSocket connections...`);
+      for (const ws of wss.clients) {
+        try {
+          ws.close(1001, 'Server shutting down');
+        } catch (err) {
+          // Ignore errors when closing WebSocket clients
+        }
+      }
+    }
+
+    // Stop accepting new connections
+    server.close(() => {
+      logger.info('HTTP server closed');
+      process.exit(0);
+    });
+
+    // Destroy all remaining connections (keep-alive, idle HTTP connections, etc.)
+    // This ensures server.close() callback fires promptly instead of waiting
+    // for clients to close their end of keep-alive connections
+    const remainingConnections = connections.size;
+    if (remainingConnections > 0) {
+      logger.info(`Closing ${remainingConnections} remaining HTTP connections...`);
+      for (const socket of connections) {
+        try {
+          socket.destroy();
+        } catch (err) {
+          // Ignore errors when destroying sockets
+        }
+      }
+      connections.clear();
+    }
+
+    // Force shutdown after 10 seconds if graceful shutdown still fails
+    setTimeout(() => {
+      logger.error('Forced shutdown after timeout');
+      process.exit(1);
+    }, 10000);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+startServer().catch(error => {
+  logger.error('FATAL: Server startup failed', error);
+  process.exit(1);
+});
+
+export default app;
+
+function setupTerminalBridge(server) {
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on('upgrade', (request, socket, head) => {
+    try {
+      const { pathname } = new URL(request.url, `http://${request.headers.host}`);
+
+      // Handle terminal WebSocket connections
+      if (pathname && pathname.startsWith('/ws/containers/')) {
+        wss.handleUpgrade(request, socket, head, (ws) => {
+          wss.emit('connection', ws, request, pathname);
+        });
+      }
+      // Handle code-server WebSocket connections
+      else if (pathname && pathname.match(/^\/tasks\/[^\/]+\/vscode/)) {
+        // Extract taskId to verify it exists
+        const match = pathname.match(/^\/tasks\/([^\/]+)\/vscode/);
+        if (match) {
+          const taskId = match[1];
+          const serverInfo = codeServerPorts.get(taskId);
+
+          if (serverInfo && serverInfo.proxy) {
+            // Extract the path we want (everything after /tasks/:id/vscode)
+            const targetPath = request.url.replace(/^\/tasks\/[^\/]+\/vscode/, '');
+
+            logger.debug('WebSocket upgrade for code-server', { taskId });
+
+            // Add error handler to socket to catch any connection issues
+            socket.on('error', (err) => {
+              logger.error('WebSocket socket error', { error: err.message, taskId });
+            });
+
+            // Modify request.url to remove the /tasks/:id/vscode prefix
+            // This way the proxy will forward the correct path to code-server
+            request.url = targetPath;
+
+            // Proxy the WebSocket upgrade (target already set in proxy instance)
+            serverInfo.proxy.ws(request, socket, head);
+          } else{
+            logger.error('Code-server not started or proxy not initialized', { taskId, pathname, hasProxy: !!serverInfo?.proxy });
+            socket.destroy();
+          }
+        } else {
+          logger.error('Could not extract taskId from WebSocket upgrade path', { pathname });
+          socket.destroy();
+        }
+      }
+      // Handle app server WebSocket connections
+      else if (pathname && pathname.match(/^\/tasks\/[^\/]+\/app\/\d+/)) {
+        // Extract taskId and port
+        const match = pathname.match(/^\/tasks\/([^\/]+)\/app\/(\d+)(\/.*)?$/);
+        if (match) {
+          const taskId = match[1];
+          const port = match[2];
+
+          const state = appServerStates.get(taskId);
+          if (!state || !state.proxies) {
+            logger.error('App server not started or proxies not initialized', { taskId, port, pathname });
+            socket.destroy();
+            return;
+          }
+
+          // Find proxy by port number
+          let proxy = null;
+          for (const [name, portInfo] of state.ports.entries()) {
+            if (portInfo.internal.toString() === port) {
+              proxy = state.proxies.get(name);
+              break;
+            }
+          }
+
+          if (proxy) {
+            // Extract the path we want (everything after /tasks/:id/app/:port)
+            const targetPath = request.url.replace(/^\/tasks\/[^\/]+\/app\/\d+/, '');
+
+            logger.debug('WebSocket upgrade for app server', { taskId, port, targetPath });
+
+            // Add error handler to socket to catch any connection issues
+            socket.on('error', (err) => {
+              logger.error('WebSocket socket error for app server', { error: err.message, taskId, port });
+            });
+
+            // Modify request.url to remove the /tasks/:id/app/:port prefix
+            // This way the proxy will forward the correct path to the app server
+            request.url = targetPath;
+
+            // Proxy the WebSocket upgrade (target already set in proxy instance)
+            proxy.ws(request, socket, head);
+          } else {
+            logger.error('App server proxy not found for port', { taskId, port, pathname });
+            socket.destroy();
+          }
+        } else {
+          logger.error('Could not extract taskId/port from app server WebSocket upgrade path', { pathname });
+          socket.destroy();
+        }
+      }
+      else {
+        // Fallback: check if this is a Vite HMR or similar WebSocket from an app server page.
+        // The browser may connect to a non-prefixed WS path. Try to route using Origin/Referer.
+        const wsReferer = request.headers.origin || request.headers.referer || '';
+        const wsRefMatch = wsReferer.match(/\/tasks\/([^\/]+)\/app\/(\d+)/);
+        let routed = false;
+
+        if (wsRefMatch) {
+          const taskId = wsRefMatch[1];
+          const port = wsRefMatch[2];
+          const state = appServerStates.get(taskId);
+
+          if (state && state.proxies) {
+            let proxy = null;
+            if (state.ports) {
+              for (const [name, portInfo] of state.ports.entries()) {
+                if (portInfo.internal.toString() === port) {
+                  proxy = state.proxies.get(name);
+                  break;
+                }
+              }
+            } else if (state.isProxyMode) {
+              // Proxy mode uses 'proxy' as the key
+              const entry = state.proxies.get('proxy');
+              proxy = entry?.proxy || entry;
+            }
+
+            if (proxy) {
+              logger.debug('WebSocket upgrade fallback via Referer/Origin', { taskId, port, pathname });
+              socket.on('error', (err) => {
+                logger.error('WebSocket socket error (fallback)', { error: err.message, taskId, port });
+              });
+              proxy.ws(request, socket, head);
+              routed = true;
+            }
+          }
+        }
+
+        if (!routed) {
+          logger.warn('Unknown WebSocket upgrade path', { pathname });
+          socket.destroy();
+        }
+      }
+    } catch (error) {
+      logger.error('Failed to handle websocket upgrade', error);
+      socket.destroy();
+    }
+  });
+
+  wss.on('connection', (ws, request, pathname) => {
+    handleTerminalConnection(ws, request, pathname).catch(error => {
+      logger.error('Terminal connection failed', error);
+      try {
+        ws.send(JSON.stringify({ type: 'error', message: error.message }));
+      } catch (sendError) {
+        logger.warn('Failed to send terminal error message', sendError);
+      }
+      ws.close(1011, 'Internal server error');
+    });
+  });
+
+  return wss;
+}
+
+async function handleTerminalConnection(ws, request, pathname) {
+  const url = new URL(request.url, `http://${request.headers.host}`);
+  const [, , , containerKeyRaw] = pathname.split('/');
+  const containerKey = decodeURIComponent(containerKeyRaw || '').trim();
+  const cmd = url.searchParams.get('cmd');
+
+  if (!containerKey) {
+    ws.send(JSON.stringify({ type: 'error', message: 'Missing container identifier' }));
+    ws.close(1008, 'Missing container identifier');
+    return;
+  }
+
+  const dockerId = resolveDockerContainerId(containerKey);
+
+  if (!dockerId) {
+    ws.send(JSON.stringify({ type: 'error', message: 'Container not found' }));
+    ws.close(1008, 'Container not found');
+    return;
+  }
+
+  const container = docker.getContainer(dockerId);
+  try {
+    await container.inspect();
+  } catch {
+    ws.send(JSON.stringify({ type: 'error', message: 'Container is not available' }));
+    ws.close(1008, 'Container is not available');
+    return;
+  }
+
+  logger.info('Opening terminal bridge', { containerKey, dockerId });
+
+  // Check if this is a task container
+  let isTaskContainer = false;
+  for (const [taskId, task] of tasks.entries()) {
+    if (task.containerId === dockerId || task.containerId?.startsWith(dockerId)) {
+      isTaskContainer = true;
+      logger.info('Attaching to task container', { taskId, containerKey });
+      break;
+    }
+  }
+
+  // If executing a command, wrap it to wait for credentials to be ready
+  let shellCmd;
+  if (cmd) {
+    // For task containers, create the credentials marker before running the command
+    // Task containers don't go through the same startup as interactive containers
+    const credentialsSetup = isTaskContainer
+      ? 'touch /tmp/.credentials-ready 2>/dev/null || true\n      '
+      : `while [ ! -f /tmp/.credentials-ready ]; do
+        sleep 0.1
+      done
+      `;
+
+    const wrappedCmd = `
+      ${credentialsSetup}${cmd}
+    `;
+    shellCmd = ['/bin/bash', '-c', wrappedCmd];
+  } else {
+    // For shell-only mode, start an interactive login shell
+    // Login shell (-l) sources ~/.profile which sources ~/.bash_env
+    // For task containers, also create ready marker
+    if (isTaskContainer) {
+      shellCmd = ['/bin/bash', '-c', 'touch /tmp/.credentials-ready 2>/dev/null || true; exec /bin/bash -l'];
+    } else {
+      shellCmd = ['/bin/bash', '-l'];
+    }
+  }
+
+  const exec = await container.exec({
+    AttachStdin: true,
+    AttachStdout: true,
+    AttachStderr: true,
+    Tty: true,
+    User: 'coder',
+    Cmd: shellCmd
+  });
+
+  const execStream = await exec.start({ hijack: true, stdin: true });
+
+  execStream.on('data', (chunk) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      // Docker exec stream includes 8-byte headers for stream multiplexing
+      // Header format: [stream_type(1), 0, 0, 0, size(4 bytes big-endian)]
+      // We need to strip these headers before sending to the client
+      let offset = 0;
+      const messages = [];
+
+      while (offset < chunk.length) {
+        if (chunk.length - offset < 8) {
+          // Incomplete header, shouldn't happen but handle gracefully
+          break;
+        }
+
+        // Read the payload size from bytes 4-7 (big-endian)
+        const size = chunk.readUInt32BE(offset + 4);
+        const payloadStart = offset + 8;
+        const payloadEnd = payloadStart + size;
+
+        if (payloadEnd > chunk.length) {
+          // Incomplete payload, shouldn't happen but handle gracefully
+          break;
+        }
+
+        // Extract just the payload (skip the 8-byte header)
+        const payload = chunk.slice(payloadStart, payloadEnd);
+        messages.push(payload.toString('utf-8'));
+
+        offset = payloadEnd;
+      }
+
+      if (messages.length > 0) {
+        ws.send(JSON.stringify({ type: 'data', data: messages.join('') }));
+      }
+    }
+  });
+
+  execStream.on('end', () => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'status', status: 'terminated' }));
+      ws.close(1000, 'Terminal session ended');
+    }
+  });
+
+  execStream.on('error', (error) => {
+    logger.error('Exec stream error', error, { containerId: dockerId });
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: 'error', message: error.message }));
+      ws.close(1011, 'Terminal stream error');
+    }
+  });
+
+  // Set up message handler BEFORE sending 'connected' status to avoid race condition
+  ws.on('message', async (message) => {
+    try {
+      const payload = JSON.parse(message.toString());
+      if (payload.type === 'data' && typeof payload.data === 'string') {
+        execStream.write(payload.data);
+      } else if (payload.type === 'resize' && Number.isFinite(payload.cols) && Number.isFinite(payload.rows)) {
+        try {
+          const rows = Math.floor(payload.rows);
+          const cols = Math.floor(payload.cols);
+          await exec.resize({ h: rows, w: cols });
+        } catch (resizeError) {
+          logger.warn('Failed to resize exec TTY', resizeError, { containerId: dockerId });
+        }
+      }
+    } catch (parseError) {
+      logger.warn('Failed to process websocket message', parseError);
+    }
+  });
+
+  ws.on('close', () => {
+    safeCloseStream(execStream);
+  });
+
+  ws.on('error', (error) => {
+    logger.warn('Websocket error', error, { containerId: dockerId });
+    safeCloseStream(execStream);
+  });
+
+  // Update task activity when terminal connects
+  for (const [taskId, task] of tasks.entries()) {
+    if (task.containerId === dockerId) {
+      task.lastActivity = new Date().toISOString();
+      logger.debug('Updated task activity for terminal connection', { taskId });
+      break;
+    }
+  }
+
+  // Send 'connected' status AFTER all handlers are set up
+  ws.send(JSON.stringify({ type: 'status', status: 'connected' }));
+}
+
+function resolveDockerContainerId(containerKey) {
+  if (!containerKey) return null;
+
+  if (containers.has(containerKey)) {
+    return containers.get(containerKey).fullContainerId;
+  }
+
+  for (const data of containers.values()) {
+    if (data.fullContainerId?.startsWith(containerKey) || data.containerId === containerKey || data.name === containerKey) {
+      return data.fullContainerId;
+    }
+  }
+
+  for (const task of tasks.values()) {
+    if (task.containerId && task.containerId.startsWith(containerKey)) {
+      return task.containerId;
+    }
+  }
+
+  return containerKey;
+}
+
+function safeCloseStream(stream) {
+  if (!stream) return;
+  try {
+    stream.end();
+  } catch (error) {
+    logger.debug('Stream end failed', { message: error.message });
+  }
+  if (typeof stream.destroy === 'function') {
+    stream.destroy();
+  }
+}
+
+/**
+ * Auto-cleanup job: Stop inactive task containers after configurable inactivity period
+ * and clean up orphaned task directories after 24 hours
+ */
+function startAutoCleanup() {
+  // Container inactivity threshold (default: 2 hours, configurable via CONTAINER_CLEANUP_HOURS)
+  const cleanupHours = parseInt(process.env.CONTAINER_CLEANUP_HOURS || '2', 10);
+  const CONTAINER_INACTIVITY_THRESHOLD = cleanupHours * 60 * 60 * 1000;
+  const TWENTY_FOUR_HOURS = 24 * 60 * 60 * 1000; // 24 hours in milliseconds
+  const CHECK_INTERVAL = 10 * 60 * 1000; // Check every 10 minutes
+
+  setInterval(async () => {
+    const now = Date.now();
+
+    // Stop inactive containers (but keep them for easy restart)
+    for (const [taskId, task] of tasks.entries()) {
+      if (!task.containerId) continue;
+
+      // Get last activity time
+      const lastActivity = task.lastActivity || task.finishedAt || task.createdAt;
+      if (!lastActivity) continue;
+
+      const lastActivityTime = new Date(lastActivity).getTime();
+      const inactiveTime = now - lastActivityTime;
+
+      // If inactive for more than threshold, stop container
+      if (inactiveTime > CONTAINER_INACTIVITY_THRESHOLD) {
+        try {
+          const container = docker.getContainer(task.containerId);
+
+          // Check if container actually exists and is running
+          let containerInfo;
+          try {
+            containerInfo = await container.inspect();
+          } catch (error) {
+            // Container doesn't exist - just clear the ID silently
+            if (error.statusCode === 404) {
+              task.containerId = null;
+              continue; // Skip to next task without logging
+            }
+            throw error; // Re-throw other errors
+          }
+
+          // Only stop if container is running
+          if (containerInfo.State.Running) {
+            logger.info('Auto-stopping inactive container', {
+              taskId,
+              containerId: task.containerId.substring(0, 12),
+              inactiveHours: (inactiveTime / (60 * 60 * 1000)).toFixed(2)
+            });
+
+            // Stop container (keep it for easy restart)
+            await container.stop({ t: 5 });
+
+            logger.info('Container stopped', { taskId });
+          }
+        } catch (error) {
+          logger.warn('Failed to auto-stop container', {
+            taskId,
+            error: error.message
+          });
+        }
+      }
+    }
+
+    // Clean up orphaned task directories (older than 24 hours with no task.json)
+    try {
+      const basePath = getBaseTaskStoragePath();
+      const dirs = await fs.readdir(basePath).catch(() => []);
+
+      for (const taskId of dirs) {
+        const { outputDir } = getTaskDirectories(taskId);
+        const taskJsonPath = path.join(outputDir, 'task.json');
+
+        try {
+          // Check if task.json exists
+          await fs.access(taskJsonPath);
+          // Task has task.json, skip it
+        } catch {
+          // No task.json - check if directory is old enough to clean
+          try {
+            const stats = await fs.stat(outputDir);
+            const age = now - stats.mtimeMs;
+
+            if (age > TWENTY_FOUR_HOURS) {
+              logger.debug('Removing orphaned task directory', {
+                taskId,
+                ageHours: (age / (60 * 60 * 1000)).toFixed(2)
+              });
+
+              await fs.rm(path.join(basePath, taskId), { recursive: true, force: true });
+            }
+          } catch {
+            // Ignore errors accessing directory stats
+          }
+        }
+      }
+    } catch (error) {
+      logger.debug('Failed to clean orphaned directories', { error: error.message });
+    }
+  }, CHECK_INTERVAL);
+
+  logger.info('Auto-cleanup job started', {
+    inactivityThreshold: `${cleanupHours} hours`,
+    orphanedDirectoryThreshold: '24 hours',
+    checkInterval: '10 minutes'
+  });
+}