@portel/photon 1.9.0 → 1.10.0

package/dist/auto-ui/beam.js

@@ -10,11 +10,9 @@ import * as net from 'net';
 import * as fs from 'fs/promises';
 import { existsSync, lstatSync, mkdirSync, realpathSync, watch } from 'fs';
 import * as path from 'path';
-import * as os from 'os';
-import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
-import { isPathWithin, isLocalRequest, setSecurityHeaders, readBody, SimpleRateLimiter, } from '../shared/security.js';
+import { setSecurityHeaders, SimpleRateLimiter } from '../shared/security.js';
 /**
  * Generate a unique ID for a photon based on its path.
  * This ensures photons with the same name from different paths are distinguishable.
@@ -25,6 +23,7 @@ function generatePhotonId(photonPath) {
 }
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+import { withTimeout } from '../async/index.js';
 // WebSocket removed - now using MCP Streamable HTTP (SSE) only
 import { listPhotonMCPs, resolvePhotonPath } from '../path-resolver.js';
 import { PhotonLoader } from '../loader.js';
@@ -32,565 +31,50 @@ import { logger, createLogger } from '../shared/logger.js';
 import { getErrorMessage } from '../shared/error-handler.js';
 import { toEnvVarName } from '../shared/config-docs.js';
 import { MarketplaceManager } from '../marketplace-manager.js';
-import { PhotonDocExtractor } from '../photon-doc-extractor.js';
-import { TemplateManager } from '../template-manager.js';
-import { subscribeChannel, pingDaemon } from '../daemon/client.js';
+import { subscribeChannel } from '../daemon/client.js';
 import { ensureDaemon } from '../daemon/manager.js';
 import { SchemaExtractor, } from '@portel/photon-core';
-import { generateOpenAPISpec } from './openapi-generator.js';
-import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, sendToSession, requestExternalElicitation, } from './streamable-http-transport.js';
-import { SDKMCPClientFactory } from '@portel/photon-core';
+import { handleStreamableHTTP, broadcastNotification, broadcastToBeam, } from './streamable-http-transport.js';
 import { getBundledPhotonPath, BEAM_BUNDLED_PHOTONS } from '../shared-utils.js';
-// SDK imports for direct resource access (transport wrapper doesn't expose these yet)
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import { ElicitRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// Config file path
-const CONFIG_FILE = process.env.PHOTON_CONFIG_FILE || path.join(os.homedir(), '.photon', 'config.json');
-// ════════════════════════════════════════════════════════════════════════════════
-// EXTERNAL MCP STATE (module-level for MCP transport access)
-// ════════════════════════════════════════════════════════════════════════════════
-/** External MCP servers loaded from config */
+// BUNDLED_PHOTONS and getBundledPhotonPath are imported from shared-utils.js
+// Extracted modules (Phase 5)
+import { loadConfig as loadConfigFromModule, saveConfig as saveConfigFromModule, migrateConfig as migrateConfigFromModule, getConfigFilePath as getConfigFilePathFromModule, } from './beam/config.js';
+import { extractClassMetadataFromSource as extractClassMetadataFromModule, applyMethodVisibility as applyMethodVisibilityFromModule, extractCspFromSource as extractCspFromModule, prettifyName as prettifyNameFromModule, prettifyToolName as prettifyToolNameFromModule, backfillEnvDefaults as backfillEnvDefaultsFromModule, } from './beam/class-metadata.js';
+import { StartupSequencer } from './beam/startup.js';
+import { SubscriptionManager } from './beam/subscription.js';
+import { handleMarketplaceRoutes } from './beam/routes/api-marketplace.js';
+import { handleBrowseRoutes } from './beam/routes/api-browse.js';
+import { handleConfigRoutes } from './beam/routes/api-config.js';
+import { loadExternalMCPs as loadExternalMCPsFromModule, reconnectExternalMCP as reconnectExternalMCPFromModule, } from './beam/external-mcp.js';
+import { configurePhotonViaMCP, reloadPhotonViaMCP, removePhotonViaMCP, updateMetadataViaMCP, generatePhotonHelpMarkdown, } from './beam/photon-management.js';
+// Delegate to extracted module
+const getConfigFilePath = getConfigFilePathFromModule;
+// Module-level state for external MCPs (shared with transport handler)
 const externalMCPs = [];
-/** Active MCP client instances for external MCPs */
 const externalMCPClients = new Map();
-/** Direct SDK clients for resource access (listResources, readResource) */
 const externalMCPSDKClients = new Map();
-/**
- * Generate a unique ID for an external MCP based on its name
- */
-function generateExternalMCPId(name) {
-    return createHash('sha256').update(`external:${name}`).digest('hex').slice(0, 12);
-}
-/**
- * Convert a tool name to a display label
- */
-function prettifyToolName(name) {
-    return name
-        .split(/[-_]/)
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join(' ');
-}
-/**
- * Create an HTTP transport for a URL-based MCP.
- * Tries Streamable HTTP first; falls back to legacy SSE.
- */
-async function connectHTTPClient(url, mcpName) {
-    const sdkClient = new Client({ name: 'beam-mcp-client', version: '1.0.0' }, {
-        capabilities: {
-            elicitation: {}, // Declare elicitation support
-            experimental: {
-                ui: {}, // Request SEP-1865 format for MCP Apps
-            },
-        },
-    });
-    // Set up elicitation handler
-    sdkClient.setRequestHandler(ElicitRequestSchema, async (request) => {
-        const params = request.params;
-        const result = await requestExternalElicitation(mcpName, {
-            mode: params.mode,
-            message: params.message,
-            requestedSchema: params.requestedSchema,
-            url: params.url,
-        });
-        return result;
-    });
-    try {
-        const transport = new StreamableHTTPClientTransport(new URL(url));
-        const connectPromise = sdkClient.connect(transport);
-        const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
-        await Promise.race([connectPromise, timeoutPromise]);
-        logger.debug(`Connected to ${url} via Streamable HTTP`);
-        return sdkClient;
-    }
-    catch (streamableError) {
-        logger.debug(`Streamable HTTP failed for ${url}, trying legacy SSE: ${streamableError}`);
-    }
-    // Fallback: legacy SSE transport
-    const sseClient = new Client({ name: 'beam-mcp-client', version: '1.0.0' }, {
-        capabilities: {
-            elicitation: {}, // Declare elicitation support
-            experimental: {
-                ui: {}, // Request SEP-1865 format for MCP Apps
-            },
-        },
-    });
-    // Set up elicitation handler for SSE client too
-    sseClient.setRequestHandler(ElicitRequestSchema, async (request) => {
-        const params = request.params;
-        const result = await requestExternalElicitation(mcpName, {
-            mode: params.mode,
-            message: params.message,
-            requestedSchema: params.requestedSchema,
-            url: params.url,
-        });
-        return result;
-    });
-    const sseTransport = new SSEClientTransport(new URL(url));
-    const connectPromise = sseClient.connect(sseTransport);
-    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
-    await Promise.race([connectPromise, timeoutPromise]);
-    logger.debug(`Connected to ${url} via legacy SSE`);
-    return sseClient;
-}
-/**
- * Load external MCPs from config.json mcpServers section
- *
- * @param config - The PhotonConfig with mcpServers section
- * @returns Array of ExternalMCPInfo objects (populated with connected status)
- */
-async function loadExternalMCPs(config) {
-    const mcpServers = config.mcpServers || {};
-    const results = [];
-    for (const [name, serverConfig] of Object.entries(mcpServers)) {
-        const mcpId = generateExternalMCPId(name);
-        // Create the MCP info with initial disconnected state
-        const mcpInfo = {
-            type: 'external-mcp',
-            id: mcpId,
-            name,
-            connected: false,
-            methods: [],
-            label: prettifyToolName(name),
-            icon: '🔌',
-            config: serverConfig,
-        };
-        try {
-            let methods = [];
-            if (serverConfig.url) {
-                // HTTP transport — SDK client only (no wrapper needed)
-                // Tries Streamable HTTP first, falls back to legacy SSE
-                const sdkClient = await connectHTTPClient(serverConfig.url, name);
-                externalMCPSDKClients.set(name, sdkClient);
-                // List tools with full metadata using SDK client
-                const toolsResult = await sdkClient.listTools();
-                const tools = toolsResult.tools || [];
-                // Convert tools to MethodInfo[] with full _meta support
-                methods = tools.map((tool) => ({
-                    name: tool.name,
-                    description: tool.description || '',
-                    params: tool.inputSchema || { type: 'object', properties: {} },
-                    returns: { type: 'object' },
-                    icon: tool['x-icon'],
-                    linkedUi: tool._meta?.ui?.resourceUri,
-                    visibility: tool._meta?.ui?.visibility,
-                }));
-                // Fetch resources to detect MCP Apps
-                try {
-                    const resourcesResult = await sdkClient.listResources();
-                    const resources = resourcesResult.resources || [];
-                    const appResources = resources.filter((r) => r.uri?.startsWith('ui://') || r.mimeType === 'application/vnd.mcp.ui+html');
-                    // Count only non-UI resources (UI resources are internal implementation detail)
-                    mcpInfo.resourceCount = resources.length - appResources.length;
-                    if (appResources.length > 0) {
-                        mcpInfo.hasApp = true;
-                        mcpInfo.appResourceUri = appResources[0].uri;
-                        mcpInfo.appResourceUris = appResources.map((r) => r.uri);
-                        const uriList = mcpInfo.appResourceUris.join(', ');
-                        logger.info(`🎨 MCP App detected: ${name} (${uriList})`);
-                    }
-                }
-                catch (resourceError) {
-                    logger.debug(`Resources not supported by ${name}`);
-                }
-                mcpInfo.connected = true;
-                mcpInfo.methods = methods;
-            }
-            else if (serverConfig.command) {
-                // Stdio transport — create wrapper client as fallback, SDK client as primary
-                const mcpConfig = {
-                    mcpServers: {
-                        [name]: serverConfig,
-                    },
-                };
-                const factory = new SDKMCPClientFactory(mcpConfig, false);
-                const client = factory.create(name);
-                externalMCPClients.set(name, client);
-                try {
-                    const sdkTransport = new StdioClientTransport({
-                        command: serverConfig.command,
-                        args: serverConfig.args,
-                        cwd: serverConfig.cwd,
-                        env: serverConfig.env,
-                        stderr: 'ignore', // Suppress stderr to avoid ugly tracebacks on shutdown
-                    });
-                    const sdkClient = new Client({ name: 'beam-mcp-client', version: '1.0.0' }, {
-                        capabilities: {
-                            elicitation: {}, // Declare elicitation support
-                            experimental: {
-                                ui: {}, // Request SEP-1865 format for MCP Apps
-                            },
-                        },
-                    });
-                    // Set up elicitation handler BEFORE connecting
-                    // This handles elicitation/create requests from the server
-                    sdkClient.setRequestHandler(ElicitRequestSchema, async (request) => {
-                        const params = request.params;
-                        const result = await requestExternalElicitation(name, {
-                            mode: params.mode,
-                            message: params.message,
-                            requestedSchema: params.requestedSchema,
-                            url: params.url,
-                        });
-                        return result;
-                    });
-                    const connectPromise = sdkClient.connect(sdkTransport);
-                    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
-                    await Promise.race([connectPromise, timeoutPromise]);
-                    externalMCPSDKClients.set(name, sdkClient);
-                    // List tools with full metadata using SDK client
-                    const toolsResult = await sdkClient.listTools();
-                    const tools = toolsResult.tools || [];
-                    // Convert tools to MethodInfo[] with full _meta support
-                    methods = tools.map((tool) => ({
-                        name: tool.name,
-                        description: tool.description || '',
-                        params: tool.inputSchema || { type: 'object', properties: {} },
-                        returns: { type: 'object' },
-                        icon: tool['x-icon'],
-                        // Preserve MCP App linkage from tool metadata
-                        linkedUi: tool._meta?.ui?.resourceUri,
-                        visibility: tool._meta?.ui?.visibility,
-                    }));
-                    // Fetch resources to detect MCP Apps
-                    try {
-                        const resourcesResult = await sdkClient.listResources();
-                        const resources = resourcesResult.resources || [];
-                        // Check for MCP App resources (ui:// scheme or application/vnd.mcp.ui+html mime)
-                        const appResources = resources.filter((r) => r.uri?.startsWith('ui://') || r.mimeType === 'application/vnd.mcp.ui+html');
-                        // Count only non-UI resources (UI resources are internal implementation detail)
-                        mcpInfo.resourceCount = resources.length - appResources.length;
-                        if (appResources.length > 0) {
-                            mcpInfo.hasApp = true;
-                            mcpInfo.appResourceUri = appResources[0].uri; // Default to first
-                            mcpInfo.appResourceUris = appResources.map((r) => r.uri);
-                            const uriList = mcpInfo.appResourceUris.join(', ');
-                            logger.info(`🎨 MCP App detected: ${name} (${uriList})`);
-                        }
-                    }
-                    catch (resourceError) {
-                        // Resources not supported - that's fine
-                        logger.debug(`Resources not supported by ${name}`);
-                    }
-                    // Set connected state after successful SDK client setup
-                    mcpInfo.connected = true;
-                    mcpInfo.methods = methods;
-                }
-                catch (sdkError) {
-                    // SDK client failed — don't fall back to wrapper for stdio MCPs
-                    // (same command would fail identically, and wrapper spawns a process
-                    // without stderr suppression, leaking raw Node.js stack traces)
-                    throw sdkError;
-                }
-            }
-            else {
-                // No command or URL — create wrapper client (legacy fallback)
-                const mcpConfig = {
-                    mcpServers: {
-                        [name]: serverConfig,
-                    },
-                };
-                const factory = new SDKMCPClientFactory(mcpConfig, false);
-                const client = factory.create(name);
-                externalMCPClients.set(name, client);
-                const tools = await client.list();
-                methods = (tools || []).map((tool) => ({
-                    name: tool.name,
-                    description: tool.description || '',
-                    params: tool.inputSchema || { type: 'object', properties: {} },
-                    returns: { type: 'object' },
-                    icon: tool['x-icon'],
-                }));
-                mcpInfo.connected = true;
-                mcpInfo.methods = methods;
-            }
-            logger.info(`🔌 Connected to external MCP: ${name} (${methods.length} tools)`);
-        }
-        catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            mcpInfo.errorMessage = errorMsg.slice(0, 200);
-            // User-friendly error messages for common failures
-            const shortMsg = errorMsg.includes('Cannot find module')
-                ? `Module not found (run npm build in the MCP directory)`
-                : errorMsg.includes('ENOENT')
-                    ? `Command not found: ${serverConfig.command}`
-                    : errorMsg.includes('Connection timeout')
-                        ? `Connection timed out (server may not be running)`
-                        : errorMsg.includes('Connection closed')
-                            ? `Server exited immediately (check configuration)`
-                            : errorMsg.slice(0, 120);
-            logger.warn(`⚠️  External MCP "${name}" — ${shortMsg}`);
-        }
-        results.push(mcpInfo);
-    }
-    return results;
-}
-/**
- * Reconnect a failed external MCP
- *
- * @param name - The MCP name to reconnect
- * @returns Success status and error message if failed
- */
-async function reconnectExternalMCP(name) {
-    const mcpIndex = externalMCPs.findIndex((m) => m.name === name);
-    if (mcpIndex === -1) {
-        return { success: false, error: `External MCP not found: ${name}` };
-    }
-    const mcp = externalMCPs[mcpIndex];
-    try {
-        let methods = [];
-        if (mcp.config.url) {
-            // HTTP transport — tries Streamable HTTP, falls back to legacy SSE
-            const sdkClient = await connectHTTPClient(mcp.config.url, name);
-            externalMCPSDKClients.set(name, sdkClient);
-            const toolsResult = await sdkClient.listTools();
-            const tools = toolsResult.tools || [];
-            methods = tools.map((tool) => ({
-                name: tool.name,
-                description: tool.description || '',
-                params: tool.inputSchema || { type: 'object', properties: {} },
-                returns: { type: 'object' },
-                icon: tool['x-icon'],
-                linkedUi: tool._meta?.ui?.resourceUri,
-                visibility: tool._meta?.ui?.visibility,
-            }));
-            // Fetch resources to detect MCP Apps
-            try {
-                const resourcesResult = await sdkClient.listResources();
-                const resources = resourcesResult.resources || [];
-                const appResources = resources.filter((r) => r.uri?.startsWith('ui://') || r.mimeType === 'application/vnd.mcp.ui+html');
-                // Count only non-UI resources (UI resources are internal implementation detail)
-                mcp.resourceCount = resources.length - appResources.length;
-                if (appResources.length > 0) {
-                    mcp.hasApp = true;
-                    mcp.appResourceUri = appResources[0].uri;
-                    mcp.appResourceUris = appResources.map((r) => r.uri);
-                }
-            }
-            catch {
-                // Resources not supported
-            }
-        }
-        else {
-            // Stdio / wrapper transport
-            const mcpConfig = {
-                mcpServers: {
-                    [name]: mcp.config,
-                },
-            };
-            const factory = new SDKMCPClientFactory(mcpConfig, false);
-            const client = factory.create(name);
-            const connectPromise = client.list();
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Connection timeout (10s)')), 10000));
-            const tools = (await Promise.race([connectPromise, timeoutPromise]));
-            methods = (tools || []).map((tool) => ({
-                name: tool.name,
-                description: tool.description || '',
-                params: tool.inputSchema || { type: 'object', properties: {} },
-                returns: { type: 'object' },
-                icon: tool['x-icon'],
-            }));
-            externalMCPClients.set(name, client);
-        }
-        // Update MCP info
-        mcp.connected = true;
-        mcp.methods = methods;
-        mcp.errorMessage = undefined;
-        logger.info(`🔌 Reconnected to external MCP: ${name} (${methods.length} tools)`);
-        return { success: true };
-    }
-    catch (error) {
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        mcp.errorMessage = errorMsg.slice(0, 200);
-        logger.warn(`⚠️ Failed to reconnect to external MCP: ${name} - ${errorMsg}`);
-        return { success: false, error: errorMsg };
-    }
-}
-/**
- * Migrate old flat config to new nested structure
- */
-function migrateConfig(config) {
-    // Already new format
-    if (config.photons !== undefined || config.mcpServers !== undefined) {
-        return {
-            photons: config.photons || {},
-            mcpServers: config.mcpServers || {},
-        };
-    }
-    // Old flat format → migrate all keys under photons
-    console.error('📦 Migrating config.json to new nested format...');
-    return {
-        photons: { ...config },
-        mcpServers: {},
-    };
-}
-async function loadConfig() {
-    try {
-        const data = await fs.readFile(CONFIG_FILE, 'utf-8');
-        const raw = JSON.parse(data);
-        const migrated = migrateConfig(raw);
-        // Save back if migration occurred (structure changed)
-        if (!raw.photons && Object.keys(raw).length > 0) {
-            await saveConfig(migrated);
-            console.error('✅ Config migrated successfully');
-        }
-        return migrated;
-    }
-    catch (error) {
-        if (error?.code === 'ENOENT') {
-            // Normal on first run — config.json doesn't exist yet
-            return { photons: {}, mcpServers: {} };
-        }
-        // Real error: JSON parse failure, permission denied, etc.
-        console.error(`⚠️ Failed to load config.json: ${error?.message || error}`);
-        return { photons: {}, mcpServers: {} };
-    }
-}
-async function saveConfig(config) {
-    const dir = path.dirname(CONFIG_FILE);
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
-}
-/**
- * Extract class-level metadata (description, icon) from JSDoc comments
- */
-/**
- * Convert a kebab-case name to a display label
- * e.g. "filesystem" → "Filesystem", "git-box" → "Git Box"
- */
-function prettifyName(name) {
-    return name
-        .split('-')
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join(' ');
-}
-/**
- * After loading a photon, backfill env vars for constructor params that used
- * their TypeScript defaults (env var not set). This ensures the env var always
- * reflects the effective value so other consumers (e.g. /api/browse) can read it.
- */
-function backfillEnvDefaults(instance, params) {
-    for (const param of params) {
-        if (!process.env[param.envVar] && param.hasDefault) {
-            const value = instance[param.name];
-            if (value !== undefined && value !== null) {
-                process.env[param.envVar] = String(value);
-            }
-        }
-    }
-}
-function extractClassMetadataFromSource(content) {
-    try {
-        // Find class-level JSDoc (immediately before class, or first JSDoc in file)
-        const classDocRegex = /\/\*\*([\s\S]*?)\*\/\s*\n?(?:export\s+)?(?:default\s+)?class\s+\w+/;
-        const match = content.match(classDocRegex) || content.match(/^\/\*\*([\s\S]*?)\*\//);
-        if (!match) {
-            return {};
-        }
-        const docContent = match[1];
-        const metadata = {};
-        // Extract @icon
-        const iconMatch = docContent.match(/@icon\s+(\S+)/);
-        if (iconMatch) {
-            metadata.icon = iconMatch[1];
-        }
-        // Extract @internal (presence indicates internal photon)
-        if (/@internal\b/.test(docContent)) {
-            metadata.internal = true;
-        }
-        // Extract @version
-        const versionMatch = docContent.match(/@version\s+(\S+)/);
-        if (versionMatch) {
-            metadata.version = versionMatch[1];
-        }
-        // Extract @author
-        const authorMatch = docContent.match(/@author\s+([^\n@]+)/);
-        if (authorMatch) {
-            metadata.author = authorMatch[1].trim();
-        }
-        // Extract @label (custom display name)
-        const labelMatch = docContent.match(/@label\s+([^\n@]+)/);
-        if (labelMatch) {
-            metadata.label = labelMatch[1].trim();
-        }
-        // Extract @description or first line of doc (not starting with @)
-        const descMatch = docContent.match(/@description\s+([^\n@]+)/);
-        if (descMatch) {
-            metadata.description = descMatch[1].trim();
-        }
-        else {
-            // Get first non-empty line that's not a tag
-            const lines = docContent
-                .split('\n')
-                .map((l) => l.replace(/^\s*\*\s?/, '').trim())
-                .filter((l) => l && !l.startsWith('@'));
-            if (lines.length > 0) {
-                metadata.description = lines[0];
-            }
-        }
-        return metadata;
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Extract @visibility annotations from method-level JSDoc and apply to methods
- * @visibility model,app → ['model', 'app']
- */
-function applyMethodVisibility(source, methods) {
-    const regex = /\/\*\*[\s\S]*?@visibility\s+([\w,\s]+)[\s\S]*?\*\/\s*(?:async\s+)?\*?\s*(\w+)/g;
-    let match;
-    while ((match = regex.exec(source)) !== null) {
-        const [, visibilityStr, methodName] = match;
-        const method = methods.find((m) => m.name === methodName);
-        if (method) {
-            method.visibility = visibilityStr
-                .split(',')
-                .map((v) => v.trim())
-                .filter((v) => v === 'model' || v === 'app');
-        }
-    }
-}
-/**
- * Extract @csp annotations from class-level JSDoc
- * @csp connect domain1,domain2
- * @csp resource cdn.example.com
- */
-function extractCspFromSource(source) {
-    const result = {};
-    // Match class-level JSDoc with @csp tags
-    const classDocRegex = /\/\*\*([\s\S]*?)\*\/\s*\n?(?:export\s+)?(?:default\s+)?class\s+(\w+)/g;
-    let classMatch;
-    while ((classMatch = classDocRegex.exec(source)) !== null) {
-        const docContent = classMatch[1];
-        const csp = {};
-        let hasCsp = false;
-        const cspRegex = /@csp\s+(connect|resource|frame|base-uri)\s+([^\n@]+)/g;
-        let cspMatch;
-        while ((cspMatch = cspRegex.exec(docContent)) !== null) {
-            hasCsp = true;
-            const directive = cspMatch[1].trim();
-            const domains = cspMatch[2]
-                .trim()
-                .split(/[,\s]+/)
-                .filter(Boolean);
-            const key = directive === 'base-uri' ? 'baseUriDomains' : `${directive}Domains`;
-            csp[key] = (csp[key] || []).concat(domains);
-        }
-        if (hasCsp) {
-            result['__class__'] = csp;
-        }
-    }
-    return result;
-}
+// Delegate to extracted module
+const prettifyToolName = prettifyToolNameFromModule;
+// Delegates — external MCP management now in beam/external-mcp.ts
+const externalMCPState = { externalMCPs, externalMCPClients, externalMCPSDKClients };
+const loadExternalMCPs = (config) => loadExternalMCPsFromModule(config, externalMCPState);
+const reconnectExternalMCP = (name) => reconnectExternalMCPFromModule(name, externalMCPState);
+// Delegates to extracted config module
+const migrateConfig = migrateConfigFromModule;
+const loadConfig = loadConfigFromModule;
+const saveConfig = saveConfigFromModule;
+// Delegates to extracted class-metadata module
+const prettifyName = prettifyNameFromModule;
+const backfillEnvDefaults = backfillEnvDefaultsFromModule;
+const extractClassMetadataFromSource = extractClassMetadataFromModule;
+const applyMethodVisibility = applyMethodVisibilityFromModule;
+const extractCspFromSource = extractCspFromModule;
 export async function startBeam(rawWorkingDir, port) {
     const workingDir = path.resolve(rawWorkingDir);
-    // Show version banner immediately
     const { PHOTON_VERSION } = await import('../version.js');
-    console.log(`\n⚡ Photon Beam v${PHOTON_VERSION}\n`);
+    // StartupSequencer manages ordered output during startup
+    const startup = new StartupSequencer(PHOTON_VERSION, workingDir);
+    const isTTY = process.stderr.isTTY;
     // Initialize marketplace manager for photon discovery and installation
     const marketplace = new MarketplaceManager();
     await marketplace.initialize();
@@ -632,14 +116,14 @@ export async function startBeam(rawWorkingDir, port) {
         logger.info('No photons found - showing management UI');
     }
     // Load saved config and apply to env
-    const savedConfig = await loadConfig();
+    const savedConfig = await loadConfig(workingDir);
     // Extract metadata for all photons
     const photons = [];
     const photonMCPs = new Map(); // Store full MCP objects
     // Use PhotonLoader with error-only logger to reduce verbosity
     // Beam handles config errors gracefully via UI forms, but we still want to see actual errors
     const errorOnlyLogger = createLogger({ level: 'error' });
-    const loader = new PhotonLoader(false, errorOnlyLogger);
+    const loader = new PhotonLoader(false, errorOnlyLogger, workingDir);
     // Counts updated after photon loading
     let configuredCount = 0;
     let unconfiguredCount = 0;
@@ -736,9 +220,7 @@ export async function startBeam(rawWorkingDir, port) {
         }
         // All params satisfied, try to load with timeout
         try {
-            const loadPromise = loader.loadFile(photonPath);
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Loading timeout (10s)')), 10000));
-            const mcp = (await Promise.race([loadPromise, timeoutPromise]));
+            const mcp = (await withTimeout(loader.loadFile(photonPath), 10000, 'Loading timeout (10s)'));
             const instance = mcp.instance;
             if (!instance) {
                 return null;
@@ -789,6 +271,18 @@ export async function startBeam(rawWorkingDir, port) {
                     });
                 }
             });
+            // Add auto-generated settings tool if the photon has `protected settings`
+            if (mcp.settingsSchema?.hasSettings) {
+                const settingsTool = mcp.tools.find((t) => t.name === 'settings');
+                if (settingsTool) {
+                    methods.push({
+                        name: 'settings',
+                        description: settingsTool.description || 'Board settings',
+                        params: settingsTool.inputSchema || { type: 'object', properties: {} },
+                        returns: { type: 'object' },
+                    });
+                }
+            }
             // Apply @visibility annotations from source to methods
             applyMethodVisibility(schemaSource, methods);
             // Check if this is an App (has main() method with @ui)
@@ -847,6 +341,7 @@ export async function startBeam(rawWorkingDir, port) {
                 promptCount,
                 installSource,
                 ...(isStateful && { stateful: true }),
+                ...(mcp.settingsSchema?.hasSettings && { hasSettings: true }),
                 ...(constructorParams.length > 0 && { requiredParams: constructorParams }),
                 ...(mcp.injectedPhotons &&
                     mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
@@ -864,166 +359,19 @@ export async function startBeam(rawWorkingDir, port) {
                 internal: isInternal,
                 requiredParams: constructorParams,
                 errorReason: constructorParams.length > 0 ? 'missing-config' : 'load-error',
-                errorMessage: errorMsg.slice(0, 200),
+                errorMessage: errorMsg.slice(0, 2000),
             };
         }
     }
-    const channelSubscriptions = new Map();
-    /** Buffer retention window — events older than this are purged */
-    const EVENT_BUFFER_DURATION_MS = 5 * 60 * 1000; // 5 minutes
-    const channelEventBuffers = new Map();
-    // Store an event in the channel buffer
-    function bufferEvent(channel, method, params) {
-        let buffer = channelEventBuffers.get(channel);
-        if (!buffer) {
-            buffer = { events: [] };
-            channelEventBuffers.set(channel, buffer);
-        }
-        const now = Date.now();
-        const event = {
-            id: now,
-            method,
-            params,
-            timestamp: now,
-        };
-        buffer.events.push(event);
-        // Purge events older than retention window
-        const cutoff = now - EVENT_BUFFER_DURATION_MS;
-        while (buffer.events.length > 0 && buffer.events[0].timestamp < cutoff) {
-            buffer.events.shift();
-        }
-        return now;
-    }
-    // Replay missed events to a specific session, or signal full sync needed
-    function replayEventsToSession(sessionId, channel, lastTimestamp) {
-        const buffer = channelEventBuffers.get(channel);
-        // No buffer = no events ever sent on this channel
-        if (!buffer || buffer.events.length === 0) {
-            return { replayed: 0, refreshNeeded: false };
-        }
-        // No lastTimestamp = client is fresh, no replay needed
-        if (lastTimestamp === undefined) {
-            return { replayed: 0, refreshNeeded: false };
-        }
-        const oldestEvent = buffer.events[0];
-        // Stale: client's timestamp is older than buffer window → full sync needed
-        if (lastTimestamp < oldestEvent.timestamp) {
-            sendToSession(sessionId, 'photon/refresh-needed', { channel });
-            logger.info(`📡 Stale client on ${channel} - last seen ${new Date(lastTimestamp).toISOString()}, oldest buffered ${new Date(oldestEvent.timestamp).toISOString()}, full sync needed`);
-            return { replayed: 0, refreshNeeded: true };
-        }
-        // Delta sync: replay events after client's last timestamp
-        const eventsToReplay = buffer.events.filter((e) => e.timestamp > lastTimestamp);
-        if (eventsToReplay.length === 0) {
-            return { replayed: 0, refreshNeeded: false };
-        }
-        for (const event of eventsToReplay) {
-            sendToSession(sessionId, event.method, { ...event.params, _eventId: event.timestamp });
-        }
-        logger.info(`📡 Delta sync: ${channel} - replayed ${eventsToReplay.length} events`);
-        return { replayed: eventsToReplay.length, refreshNeeded: false };
-    }
+    // Photon loading is deferred until after server.listen() — see end of startBeam()
     // ══════════════════════════════════════════════════════════════════════════════
-    // Subscribe to a channel (increment ref count, actually subscribe if first)
-    // Channel format: {photonId}:{itemId} (e.g., "a3f2b1c4d5e6:photon")
-    async function subscribeToChannel(channel) {
-        const existing = channelSubscriptions.get(channel);
-        if (existing) {
-            existing.refCount++;
-            logger.debug(`Channel ${channel} ref count: ${existing.refCount}`);
-            return;
-        }
-        // First subscriber - actually subscribe to daemon
-        const subscription = { refCount: 1, unsubscribe: null };
-        channelSubscriptions.set(channel, subscription);
-        try {
-            // Extract photonId and itemId from channel (e.g., "a3f2b1:photon" -> photonId, itemId)
-            const [photonId, itemId] = channel.split(':');
-            // Look up photon name from ID
-            const photon = photons.find((p) => p.id === photonId);
-            if (!photon) {
-                logger.warn(`Cannot subscribe to ${channel}: unknown photon ID ${photonId}`);
-                return;
-            }
-            const photonName = photon.name;
-            // Daemon uses photonName:itemId as channel (not photonId)
-            const daemonChannel = `${photonName}:${itemId}`;
-            const isRunning = await pingDaemon(photonName);
-            if (isRunning) {
-                const unsubscribe = await subscribeChannel(photonName, daemonChannel, (message) => {
-                    // Forward channel messages as events with delta
-                    // Include both photonId (for client) and photonName (for display)
-                    const params = {
-                        photonId,
-                        photon: photonName,
-                        channel: daemonChannel,
-                        event: message?.event,
-                        data: message?.data || message,
-                    };
-                    // Buffer event for replay on reconnect
-                    const eventId = bufferEvent(channel, 'photon/channel-event', params);
-                    broadcastToBeam('photon/channel-event', { ...params, _eventId: eventId });
-                });
-                subscription.unsubscribe = unsubscribe;
-                logger.info(`📡 Subscribed to ${daemonChannel} (id: ${photonId}, ref: 1)`);
-            }
-        }
-        catch {
-            // Daemon not running - that's fine, in-process events still work
-        }
-    }
-    // Unsubscribe from a channel (decrement ref count, actually unsubscribe if last)
-    function unsubscribeFromChannel(channel) {
-        const subscription = channelSubscriptions.get(channel);
-        if (!subscription)
-            return;
-        subscription.refCount--;
-        logger.debug(`Channel ${channel} ref count: ${subscription.refCount}`);
-        if (subscription.refCount <= 0) {
-            // Last subscriber - actually unsubscribe
-            if (subscription.unsubscribe) {
-                subscription.unsubscribe();
-                logger.info(`📡 Unsubscribed from ${channel}`);
-            }
-            channelSubscriptions.delete(channel);
-        }
-    }
-    // Track what each session is viewing for cleanup on disconnect
-    // Uses photonId (hash) for unique identification across servers
-    const sessionViewState = new Map();
-    // Called when a client starts viewing a board (from MCP notification)
-    // photonId: hash of photon path (unique across servers)
-    // itemId: whatever the photon uses to identify the item (e.g., board name)
-    // lastTimestamp: optional - if provided, delta sync missed events or signal full sync needed
-    function onClientViewingBoard(sessionId, photonId, itemId, lastTimestamp) {
-        const prevState = sessionViewState.get(sessionId);
-        // Unsubscribe from previous item if different
-        if (prevState?.itemId && (prevState.photonId !== photonId || prevState.itemId !== itemId)) {
-            const prevChannel = `${prevState.photonId}:${prevState.itemId}`;
-            unsubscribeFromChannel(prevChannel);
-        }
-        // Subscribe to new item
-        const channel = `${photonId}:${itemId}`;
-        sessionViewState.set(sessionId, { photonId, itemId });
-        subscribeToChannel(channel);
-        // Delta sync missed events if lastTimestamp is provided
-        if (lastTimestamp !== undefined) {
-            replayEventsToSession(sessionId, channel, lastTimestamp);
-        }
-    }
-    // Called when a client disconnects
-    function onClientDisconnect(sessionId) {
-        const state = sessionViewState.get(sessionId);
-        if (state?.photonId && state?.itemId) {
-            const channel = `${state.photonId}:${state.itemId}`;
-            unsubscribeFromChannel(channel);
-        }
-        sessionViewState.delete(sessionId);
-    }
+    // Subscription management (ref-counted channels + event buffer replay)
+    const subMgr = new SubscriptionManager({ photons, workingDir });
     const subscriptionManager = {
-        onClientViewingBoard,
-        onClientDisconnect,
+        onClientViewingBoard: subMgr.onClientViewingBoard.bind(subMgr),
+        onClientDisconnect: subMgr.onClientDisconnect.bind(subMgr),
     };
+    const bufferEvent = subMgr.bufferEvent.bind(subMgr);
     // UI asset loader for MCP resources/read
     const loadUIAsset = async (photonName, uiId) => {
         const photon = photons.find((p) => p.name === photonName);
@@ -1047,1272 +395,178 @@ export async function startBeam(rawWorkingDir, port) {
     };
     // Security: rate limiter for API endpoints
     const apiRateLimiter = new SimpleRateLimiter(30, 60_000);
+    // Shared state object for extracted route modules.
+    // Actions are assigned later (after broadcastPhotonChange/handleFileChange are defined)
+    // but before the server starts accepting connections — closures capture the reference.
+    const beamActions = {
+        broadcastPhotonChange: () => broadcastPhotonChange(),
+        handleFileChange: (name) => handleFileChange(name),
+        loadSinglePhoton: (name) => loadSinglePhoton(name),
+        reconnectExternalMCP: (name) => reconnectExternalMCP(name),
+        loadUIAsset: (photonName, uiId) => loadUIAsset(photonName, uiId),
+        subscribeToChannel: async () => { },
+        unsubscribeFromChannel: () => { },
+        configurePhotonViaMCP: async () => { },
+        reloadPhotonViaMCP: async () => { },
+        removePhotonViaMCP: async () => { },
+    };
+    const beamState = {
+        actions: beamActions,
+        workingDir,
+        ctx: null, // Not yet used by route modules
+        loader,
+        marketplace,
+        savedConfig,
+        photons,
+        photonMCPs,
+        externalMCPs,
+        externalMCPClients,
+        externalMCPSDKClients,
+        channelSubscriptions: new Map(),
+        channelEventBuffers: new Map(),
+        sessionViewState: new Map(),
+        apiRateLimiter,
+        server: null,
+        watchers: [],
+        pendingReloads: new Map(),
+        activeLoads: new Set(),
+        pendingAfterLoad: new Map(),
+        beamDir: __dirname,
+        configuredCount: 0,
+        unconfiguredCount: 0,
+    };
     // Create HTTP server
-    const server = http.createServer(async (req, res) => {
-        // Security: set standard security headers on all responses
-        setSecurityHeaders(res);
-        const url = new URL(req.url || '/', `http://${req.headers.host}`);
-        // ══════════════════════════════════════════════════════════════════════════
-        // MCP Streamable HTTP Transport (standard MCP clients like Claude Desktop)
-        // Endpoint: /mcp (POST for requests, GET for SSE notifications)
-        // ══════════════════════════════════════════════════════════════════════════
-        if (url.pathname === '/mcp') {
-            const handled = await handleStreamableHTTP(req, res, {
-                photons, // Pass all photons including unconfigured for configurationSchema
-                photonMCPs,
-                externalMCPs,
-                externalMCPClients,
-                externalMCPSDKClients, // SDK clients for tool calls with structuredContent
-                reconnectExternalMCP,
-                loadUIAsset,
-                configurePhoton: async (photonName, config) => {
-                    return configurePhotonViaMCP(photonName, config, photons, photonMCPs, loader, savedConfig);
-                },
-                reloadPhoton: async (photonName) => {
-                    return reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, savedConfig, broadcastPhotonChange);
-                },
-                removePhoton: async (photonName) => {
-                    return removePhotonViaMCP(photonName, photons, photonMCPs, savedConfig, broadcastPhotonChange);
-                },
-                updateMetadata: async (photonName, methodName, metadata) => {
-                    return updateMetadataViaMCP(photonName, methodName, metadata, photons);
-                },
-                generatePhotonHelp: async (photonName) => {
-                    return generatePhotonHelpMarkdown(photonName, photons);
-                },
-                loader, // Pass loader for proper execution context (this.emit() support)
-                subscriptionManager, // For on-demand channel subscriptions
-                broadcast: (message) => {
-                    const msg = message;
-                    // Forward JSON-RPC notifications (progress, status, etc.)
-                    if (msg.jsonrpc === '2.0' && msg.method) {
-                        broadcastNotification(msg.method, msg.params || {});
-                    }
-                    // Forward channel events (task-moved, task-updated, etc.) with delta
-                    else if (msg.type === 'channel-event') {
-                        const params = {
-                            photon: msg.photon,
-                            channel: msg.channel,
-                            event: msg.event,
-                            data: msg.data,
-                        };
-                        // Buffer event for replay - find photonId from name for consistent channel key
-                        const photon = photons.find((p) => p.name === msg.photon);
-                        if (photon && msg.channel) {
-                            const [, itemId] = msg.channel.split(':');
-                            const bufferChannel = `${photon.id}:${itemId}`;
-                            const eventId = bufferEvent(bufferChannel, 'photon/channel-event', {
-                                ...params,
-                                photonId: photon.id,
-                            });
-                            broadcastToBeam('photon/channel-event', {
-                                ...params,
-                                photonId: photon.id,
-                                _eventId: eventId,
-                            });
-                        }
-                        else {
-                            broadcastToBeam('photon/channel-event', params);
-                        }
-                    }
-                    // Forward board-update for backwards compatibility
-                    else if (msg.type === 'board-update') {
-                        broadcastToBeam('photon/board-update', {
-                            photon: msg.photon,
-                            board: msg.board,
-                        });
-                    }
-                },
-            });
-            if (handled)
-                return;
-        }
-        // Serve static frontend bundle
-        if (url.pathname === '/beam.bundle.js') {
-            try {
-                const bundlePath = path.join(__dirname, '../../dist/beam.bundle.js');
-                const content = await fs.readFile(bundlePath, 'utf-8');
-                res.writeHead(200, { 'Content-Type': 'text/javascript' });
-                res.end(content);
-            }
-            catch {
-                res.writeHead(404);
-                res.end('Bundle not found. Run npm run build:beam first.');
-            }
-            return;
-        }
-        // Default route: Serve Lit App
-        if (url.pathname === '/' || !url.pathname.startsWith('/api')) {
-            try {
-                const indexPath = path.join(__dirname, 'frontend/index.html');
-                const content = await fs.readFile(indexPath, 'utf-8');
-                res.writeHead(200, { 'Content-Type': 'text/html' });
-                res.end(content);
-            }
-            catch (err) {
-                res.writeHead(500);
-                res.end('Error serving UI: ' + String(err));
-            }
-            return;
-        }
-        // File browser API
-        if (url.pathname === '/api/browse') {
-            res.setHeader('Content-Type', 'application/json');
-            let root = url.searchParams.get('root');
-            // Resolve photon's workdir as root constraint
-            const photonParam = url.searchParams.get('photon');
-            if (photonParam && !root) {
-                const envPrefix = photonParam.toUpperCase().replace(/-/g, '_');
-                const workdirEnv = process.env[`${envPrefix}_WORKDIR`];
-                if (workdirEnv) {
-                    root = path.resolve(workdirEnv);
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            const reqStart = Date.now();
+            // Security: set standard security headers on all responses
+            setSecurityHeaders(res);
+            const url = new URL(req.url || '/', `http://${req.headers.host}`);
+            // Access logging for API and MCP routes (debug-level to avoid noise)
+            res.on('finish', () => {
+                if (url.pathname.startsWith('/api/') || url.pathname === '/mcp') {
+                    const duration = Date.now() - reqStart;
+                    logger.debug(`${req.method} ${url.pathname} ${res.statusCode} ${duration}ms`);
                 }
-            }
-            // Security: default browse root to workingDir if not specified
-            if (!root) {
-                root = workingDir;
-            }
-            const dirPath = url.searchParams.get('path') || root;
-            try {
-                const resolved = path.resolve(dirPath);
-                // Security: always enforce path boundary using isPathWithin
-                if (!isPathWithin(resolved, root)) {
-                    res.writeHead(403);
-                    res.end(JSON.stringify({ error: 'Access denied: outside allowed directory' }));
-                    return;
-                }
-                const stat = await fs.stat(resolved);
-                if (!stat.isDirectory()) {
-                    res.writeHead(400);
-                    res.end(JSON.stringify({ error: 'Not a directory' }));
-                    return;
-                }
-                const entries = await fs.readdir(resolved, { withFileTypes: true });
-                const items = entries
-                    .filter((e) => !e.name.startsWith('.') || e.name === '.photon')
-                    .map((e) => ({
-                    name: e.name,
-                    path: path.join(resolved, e.name),
-                    isDirectory: e.isDirectory(),
-                }))
-                    .sort((a, b) => {
-                    if (a.isDirectory !== b.isDirectory)
-                        return a.isDirectory ? -1 : 1;
-                    return a.name.localeCompare(b.name);
-                });
-                res.writeHead(200);
-                res.end(JSON.stringify({
-                    path: resolved,
-                    parent: path.dirname(resolved),
-                    root: root ? path.resolve(root) : null,
-                    items,
-                }));
-            }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to read directory' }));
-            }
-            return;
-        }
-        // Serve a local file (for relative image paths in markdown previews, etc.)
-        if (url.pathname === '/api/local-file') {
-            const filePath = url.searchParams.get('path');
-            if (!filePath) {
-                res.writeHead(400);
-                res.end('Missing path parameter');
-                return;
-            }
-            const resolved = path.resolve(filePath);
-            // Security: prevent path traversal — file must be within working directory
-            if (!isPathWithin(resolved, workingDir)) {
-                res.writeHead(403);
-                res.end('Access denied: outside allowed directory');
-                return;
-            }
-            try {
-                const fileStat = await fs.stat(resolved);
-                if (!fileStat.isFile()) {
-                    res.writeHead(400);
-                    res.end('Not a file');
-                    return;
-                }
-                // Determine MIME type from extension
-                const ext = path.extname(resolved).toLowerCase();
-                const mimeTypes = {
-                    '.png': 'image/png',
-                    '.jpg': 'image/jpeg',
-                    '.jpeg': 'image/jpeg',
-                    '.gif': 'image/gif',
-                    '.svg': 'image/svg+xml',
-                    '.webp': 'image/webp',
-                    '.ico': 'image/x-icon',
-                    '.bmp': 'image/bmp',
-                    '.avif': 'image/avif',
-                    '.pdf': 'application/pdf',
-                };
-                const contentType = mimeTypes[ext] || 'application/octet-stream';
-                const data = await fs.readFile(resolved);
-                res.writeHead(200, {
-                    'Content-Type': contentType,
-                    'Content-Length': data.length,
-                    'Cache-Control': 'public, max-age=300',
-                });
-                res.end(data);
-            }
-            catch {
-                res.writeHead(404);
-                res.end('File not found');
-            }
-            return;
-        }
-        // Get photon's workdir (if applicable)
-        if (url.pathname === '/api/photon-workdir') {
-            res.setHeader('Content-Type', 'application/json');
-            const photonName = url.searchParams.get('name');
-            // If no photon name provided, just return the default working directory
-            if (!photonName) {
-                res.writeHead(200);
-                res.end(JSON.stringify({
-                    defaultWorkdir: workingDir,
-                }));
-                return;
-            }
-            const photon = photons.find((p) => p.name === photonName);
-            if (!photon) {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: 'Photon not found' }));
-                return;
-            }
-            // For filesystem photon, use BEAM's working directory
-            // This ensures the file browser shows the same files BEAM is managing
-            let photonWorkdir = null;
-            if (photonName === 'filesystem') {
-                photonWorkdir = workingDir;
-            }
-            res.writeHead(200);
-            res.end(JSON.stringify({
-                name: photonName,
-                workdir: photonWorkdir,
-                defaultWorkdir: workingDir,
-            }));
-            return;
-        }
-        // Serve UI templates for custom UI rendering
-        if (url.pathname === '/api/ui') {
-            const photonName = url.searchParams.get('photon');
-            const uiId = url.searchParams.get('id');
-            if (!photonName || !uiId) {
-                res.writeHead(400);
-                res.end(JSON.stringify({ error: 'Missing photon or id parameter' }));
-                return;
-            }
-            const photon = photons.find((p) => p.name === photonName);
-            if (!photon) {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: 'Photon not found' }));
-                return;
-            }
-            // UI templates are in <photon-dir>/<photon-name>/ui/<id>.html
-            const photonDir = path.dirname(photon.path);
-            // Try to use resolved path from assets if available (respects JSDoc)
-            const asset = photon.assets?.ui?.find((u) => u.id === uiId);
-            let uiPath;
-            if (asset && asset.resolvedPath) {
-                uiPath = asset.resolvedPath;
-            }
-            else {
-                uiPath = path.join(photonDir, photonName, 'ui', `${uiId}.html`);
-            }
-            try {
-                const uiContent = await fs.readFile(uiPath, 'utf-8');
-                res.setHeader('Content-Type', 'text/html');
-                res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-                res.writeHead(200);
-                res.end(uiContent);
-            }
-            catch {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: `UI template not found: ${uiId}` }));
-            }
-            return;
-        }
-        // Serve MCP App HTML from external MCPs with MCP Apps Extension
-        if (url.pathname === '/api/mcp-app') {
-            const mcpName = url.searchParams.get('mcp');
-            const resourceUri = url.searchParams.get('uri');
-            if (!mcpName || !resourceUri) {
-                res.writeHead(400);
-                res.end(JSON.stringify({ error: 'Missing mcp or uri parameter' }));
-                return;
-            }
-            const sdkClient = externalMCPSDKClients.get(mcpName);
-            if (!sdkClient) {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: `MCP not found or no SDK client: ${mcpName}` }));
-                return;
-            }
-            try {
-                const resourceResult = await sdkClient.readResource({ uri: resourceUri });
-                const content = resourceResult.contents?.[0];
-                if (!content) {
-                    res.writeHead(404);
-                    res.end(JSON.stringify({ error: `Resource not found: ${resourceUri}` }));
-                    return;
-                }
-                // Content can have either text or blob
-                const contentText = 'text' in content ? content.text : null;
-                const contentBlob = 'blob' in content ? content.blob : null;
-                if (!contentText && !contentBlob) {
-                    res.writeHead(404);
-                    res.end(JSON.stringify({ error: `Resource has no content: ${resourceUri}` }));
-                    return;
-                }
-                res.setHeader('Content-Type', content.mimeType || 'text/html');
-                res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-                res.writeHead(200);
-                if (contentText) {
-                    res.end(contentText);
-                }
-                else if (contentBlob) {
-                    // blob is base64 encoded
-                    res.end(Buffer.from(contentBlob, 'base64'));
-                }
-            }
-            catch (error) {
-                logger.error(`Failed to read MCP App resource: ${error}`);
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: `Failed to read resource: ${error}` }));
-            }
-            return;
-        }
-        // Serve @ui template files (class-level custom UI)
-        if (url.pathname === '/api/template') {
-            const photonName = url.searchParams.get('photon');
-            const templatePathParam = url.searchParams.get('path');
-            if (!photonName) {
-                res.writeHead(400);
-                res.end(JSON.stringify({ error: 'Missing photon parameter' }));
-                return;
-            }
-            const photon = photons.find((p) => p.name === photonName);
-            if (!photon || !photon.configured) {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: 'Photon not found or not configured' }));
-                return;
-            }
-            // Use provided path or photon's templatePath
-            const templateFile = templatePathParam || photon.templatePath;
-            if (!templateFile) {
-                res.writeHead(400);
-                res.end(JSON.stringify({ error: 'No template path specified' }));
-                return;
-            }
-            // Resolve template path relative to photon's directory
-            const photonDir = path.dirname(photon.path);
-            // Security: reject absolute template paths — must be relative to photon dir
-            if (path.isAbsolute(templateFile)) {
-                res.writeHead(403);
-                res.end(JSON.stringify({ error: 'Absolute template paths are not allowed' }));
-                return;
-            }
-            const fullTemplatePath = path.join(photonDir, templateFile);
-            // Security: validate resolved path is within photon directory
-            if (!isPathWithin(fullTemplatePath, photonDir)) {
-                res.writeHead(403);
-                res.end(JSON.stringify({ error: 'Template path traversal detected' }));
-                return;
-            }
-            try {
-                const templateContent = await fs.readFile(fullTemplatePath, 'utf-8');
-                res.setHeader('Content-Type', 'text/html');
-                res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-                res.writeHead(200);
-                res.end(templateContent);
-            }
-            catch {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: `Template not found: ${templateFile}` }));
-            }
-            return;
-        }
-        // PWA Manifest - Auto-generated for any photon
-        if (url.pathname === '/api/pwa/manifest.json') {
-            const photonName = url.searchParams.get('photon');
-            if (!photonName) {
-                res.writeHead(400);
-                res.end(JSON.stringify({ error: 'Missing photon parameter' }));
-                return;
-            }
-            const photon = photons.find((p) => p.name === photonName);
-            const displayName = photon?.name || photonName;
-            const description = photon?.description || `${displayName} - Photon App`;
-            const manifest = {
-                name: displayName,
-                short_name: displayName,
-                description,
-                start_url: `/api/pwa/app?photon=${encodeURIComponent(photonName)}`,
-                display: 'standalone',
-                background_color: '#1a1a1a',
-                theme_color: '#1a1a1a',
-                orientation: 'any',
-                icons: [
-                    {
-                        src: `/api/pwa/icon.svg?photon=${encodeURIComponent(photonName)}`,
-                        sizes: 'any',
-                        type: 'image/svg+xml',
-                        purpose: 'any',
-                    },
-                ],
-                categories: ['developer', 'utilities'],
-            };
-            res.setHeader('Content-Type', 'application/manifest+json');
-            res.writeHead(200);
-            res.end(JSON.stringify(manifest, null, 2));
-            return;
-        }
-        // PWA Icon - Auto-generated SVG from photon emoji
-        if (url.pathname === '/api/pwa/icon.svg') {
-            const photonName = url.searchParams.get('photon');
-            const photon = photons.find((p) => p.name === photonName);
-            const emoji = photon?.icon || '📦';
-            const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
-  <rect width="100" height="100" rx="20" fill="#1a1a1a"/>
-  <text x="50" y="50" font-size="50" text-anchor="middle" dominant-baseline="central">${emoji}</text>
-</svg>`;
-            res.setHeader('Content-Type', 'image/svg+xml');
-            res.writeHead(200);
-            res.end(svg);
-            return;
-        }
-        // PWA App Entry - Serves the photon UI with PWA tags injected
-        if (url.pathname === '/api/pwa/app') {
-            const photonName = url.searchParams.get('photon');
-            if (!photonName) {
-                res.writeHead(400);
-                res.end('Missing photon parameter');
-                return;
-            }
-            const photon = photons.find((p) => p.name === photonName);
-            if (!photon) {
-                res.writeHead(404);
-                res.end(`Photon not found: ${photonName}`);
-                return;
-            }
-            const displayName = photon.name;
-            const emoji = photon?.icon || '📦';
-            const uiAssets = photon.assets?.ui || [];
-            const asset = uiAssets.find((u) => u.linkedTool === 'main') || uiAssets[0];
-            const uiId = asset?.id || 'main';
-            // PWA Host page - embeds photon UI in iframe, handles postMessage
-            const pwaHost = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${emoji} ${displayName}</title>
-  <link rel="manifest" href="/api/pwa/manifest.json?photon=${encodeURIComponent(photonName)}">
-  <meta name="theme-color" content="#1a1a1a">
-  <meta name="mobile-web-app-capable" content="yes">
-  <meta name="apple-mobile-web-app-capable" content="yes">
-  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
-  <meta name="apple-mobile-web-app-title" content="${displayName}">
-  <link rel="apple-touch-icon" href="/api/pwa/icon.svg?photon=${encodeURIComponent(photonName)}">
-  <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    html, body { min-height: 100%; background: #1a1a1a; font-family: system-ui, sans-serif; color: #e5e5e5; }
-    .app-container { display: flex; flex-direction: column; min-height: 100vh; }
-    .app-frame { flex: 1; min-height: 80vh; }
-    iframe { width: 100%; height: 100%; min-height: 80vh; border: none; }
-
-    .offline {
-      display: none;
-      height: 100vh;
-      flex-direction: column;
-      align-items: center;
-      justify-content: center;
-      color: #888;
-      text-align: center;
-      padding: 40px;
-    }
-    .offline.show { display: flex; }
-    .offline h1 { font-size: 48px; margin-bottom: 20px; }
-    .offline p { font-size: 18px; margin-bottom: 30px; max-width: 400px; line-height: 1.6; }
-    .offline code {
-      background: #2a2a2a;
-      padding: 12px 24px;
-      border-radius: 8px;
-      font-size: 16px;
-      color: #4ade80;
-      font-family: monospace;
-    }
-    .offline .retry {
-      margin-top: 20px;
-      padding: 10px 20px;
-      background: #333;
-      border: none;
-      border-radius: 6px;
-      color: #fff;
-      cursor: pointer;
-      font-size: 14px;
-    }
-    .offline .retry:hover { background: #444; }
-  </style>
-</head>
-<body>
-  <div id="offline" class="offline">
-    <h1>${emoji}</h1>
-    <p>Server is not running. Start Photon to use ${displayName}:</p>
-    <code>photon</code>
-    <button class="retry" onclick="location.reload()">Retry</button>
-  </div>
-
-  <div class="app-container" id="app-container" style="display:none">
-    <iframe id="app"></iframe>
-  </div>
-
-  <script>
-    const iframe = document.getElementById('app');
-    const offline = document.getElementById('offline');
-    const appContainer = document.getElementById('app-container');
-    const photonName = '${photonName}';
-    const uiId = '${uiId}';
-
-    // Load UI with platform bridge injected
-    async function loadApp() {
-      try {
-        // Fetch UI template and platform bridge
-        const [uiRes, bridgeRes] = await Promise.all([
-          fetch('/api/ui?photon=' + encodeURIComponent(photonName) + '&id=' + encodeURIComponent(uiId)),
-          fetch('/api/platform-bridge?photon=' + encodeURIComponent(photonName) + '&method=' + encodeURIComponent(uiId) + '&theme=dark')
-        ]);
-
-        if (!uiRes.ok) {
-          offline.classList.add('show');
-          return;
-        }
-
-        let html = await uiRes.text();
-        const bridge = bridgeRes.ok ? await bridgeRes.text() : '';
-
-        // Inject platform bridge before </head>
-        html = html.replace('</head>', bridge + '</head>');
-
-        // Create blob URL and load in iframe
-        const blob = new Blob([html], { type: 'text/html' });
-        iframe.src = URL.createObjectURL(blob);
-        appContainer.style.display = 'flex';
-        initBridge();
-      } catch (e) {
-        offline.classList.add('show');
-      }
-    }
-
-    function initBridge() {
-      // Listen for messages from iframe
-      window.addEventListener('message', async (e) => {
-        const msg = e.data;
-        if (!msg || typeof msg !== 'object') return;
-
-        // Handle JSON-RPC tools/call from iframe
-        if (msg.jsonrpc === '2.0' && msg.method === 'tools/call' && msg.id != null) {
-          const { name: toolName, arguments: toolArgs } = msg.params || {};
-          try {
-            const res = await fetch('/api/invoke', {
-              method: 'POST',
-              headers: { 'Content-Type': 'application/json' },
-              body: JSON.stringify({ photon: photonName, method: toolName, args: toolArgs || {} }),
-              signal: AbortSignal.timeout(60000), // 60s for method calls
             });
-            const data = await res.json();
-            iframe.contentWindow.postMessage({
-              jsonrpc: '2.0',
-              id: msg.id,
-              result: data.error ? undefined : (data.result !== undefined ? data.result : data),
-              error: data.error ? { code: -32000, message: data.error } : undefined,
-            }, '*');
-          } catch (err) {
-            iframe.contentWindow.postMessage({
-              jsonrpc: '2.0',
-              id: msg.id,
-              error: { code: -32000, message: err.message },
-            }, '*');
-          }
-        }
-      });
-
-      // Send init message to iframe once loaded
-      iframe.onload = () => {
-        iframe.contentWindow.postMessage({
-          type: 'photon:init',
-          context: { photon: photonName, theme: 'dark', displayMode: 'fullscreen' }
-        }, '*');
-      };
-    }
-
-    loadApp();
-  </script>
-</body>
-</html>`;
-            res.setHeader('Content-Type', 'text/html');
-            res.writeHead(200);
-            res.end(pwaHost);
-            return;
-        }
-        // Invoke API: Direct HTTP endpoint for method invocation (used by PWA)
-        if (url.pathname === '/api/invoke' && req.method === 'POST') {
-            // Security: only allow local requests
-            if (!isLocalRequest(req)) {
-                res.writeHead(403);
-                res.end(JSON.stringify({ error: 'Forbidden: non-local request' }));
-                return;
-            }
-            // Security: rate limiting
-            const clientKey = req.socket?.remoteAddress || 'unknown';
-            if (!apiRateLimiter.isAllowed(clientKey)) {
-                res.writeHead(429);
-                res.end(JSON.stringify({ error: 'Too many requests' }));
-                return;
-            }
-            try {
-                const body = await readBody(req);
-                const { photon: photonName, method, args } = JSON.parse(body);
-                if (!photonName || !method) {
-                    res.writeHead(400);
-                    res.end(JSON.stringify({ error: 'Missing photon or method' }));
-                    return;
-                }
-                const mcp = photonMCPs.get(photonName);
-                if (!mcp || !mcp.instance) {
-                    res.writeHead(404);
-                    res.end(JSON.stringify({ error: `Photon not found: ${photonName}` }));
-                    return;
-                }
-                if (typeof mcp.instance[method] !== 'function') {
-                    res.writeHead(404);
-                    res.end(JSON.stringify({ error: `Method not found: ${method}` }));
-                    return;
-                }
-                const result = await mcp.instance[method](args || {});
-                res.setHeader('Content-Type', 'application/json');
-                res.writeHead(200);
-                res.end(JSON.stringify({ result }));
-            }
-            catch (err) {
-                const status = err.message?.includes('too large') ? 413 : 500;
-                res.setHeader('Content-Type', 'application/json');
-                res.writeHead(status);
-                res.end(JSON.stringify({ error: err.message || String(err) }));
-            }
-            return;
-        }
-        // Platform Bridge API: Generate platform compatibility script
-        // Uses the unified bridge architecture based on @modelcontextprotocol/ext-apps SDK
-        if (url.pathname === '/api/platform-bridge') {
-            const theme = (url.searchParams.get('theme') || 'dark');
-            const photonName = url.searchParams.get('photon') || '';
-            const methodName = url.searchParams.get('method') || '';
-            // Look up injected photons for this photon
-            const photon = photons.find((p) => p.name === photonName);
-            const injectedPhotonsList = photon && photon.configured && photon.injectedPhotons;
-            const { generateBridgeScript } = await import('./bridge/index.js');
-            const script = generateBridgeScript({
-                theme,
-                locale: 'en-US',
-                photon: photonName,
-                method: methodName,
-                hostName: 'beam',
-                hostVersion: '1.5.0',
-                injectedPhotons: injectedPhotonsList || [],
-            });
-            res.setHeader('Content-Type', 'text/html');
-            res.writeHead(200);
-            res.end(script);
-            return;
-        }
-        // Diagnostics endpoint: server health and photon status
-        if (url.pathname === '/api/diagnostics') {
-            res.setHeader('Content-Type', 'application/json');
-            try {
-                const { PHOTON_VERSION } = await import('../version.js');
-                const sources = marketplace.getAll();
-                const photonStatus = photons.map((p) => ({
-                    name: p.name,
-                    status: p.configured ? 'loaded' : 'unconfigured',
-                    methods: p.configured ? p.methods.length : 0,
-                    error: !p.configured ? p.errorMessage : undefined,
-                    internal: p.internal || undefined,
-                    path: p.path || undefined,
-                }));
-                res.writeHead(200);
-                res.end(JSON.stringify({
-                    nodeVersion: process.version,
-                    photonVersion: PHOTON_VERSION,
+            // ══════════════════════════════════════════════════════════════════════════
+            // MCP Streamable HTTP Transport (standard MCP clients like Claude Desktop)
+            // Endpoint: /mcp (POST for requests, GET for SSE notifications)
+            // ══════════════════════════════════════════════════════════════════════════
+            if (url.pathname === '/mcp') {
+                const handled = await handleStreamableHTTP(req, res, {
+                    photons, // Pass all photons including unconfigured for configurationSchema
+                    photonMCPs,
+                    externalMCPs,
+                    externalMCPClients,
+                    externalMCPSDKClients, // SDK clients for tool calls with structuredContent
+                    reconnectExternalMCP,
+                    loadUIAsset,
                     workingDir,
-                    uptime: process.uptime(),
-                    photonCount: photons.length,
-                    configuredCount: photons.filter((p) => p.configured).length,
-                    unconfiguredCount: photons.filter((p) => !p.configured).length,
-                    marketplaceSources: sources.filter((s) => s.enabled).length,
-                    photons: photonStatus,
-                }));
-            }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to generate diagnostics' }));
-            }
-            return;
-        }
-        // MCP Config Export endpoint: generate Claude Desktop config snippet
-        if (url.pathname === '/api/export/mcp-config') {
-            res.setHeader('Content-Type', 'application/json');
-            const photonName = url.searchParams.get('photon');
-            if (!photonName) {
-                res.writeHead(400);
-                res.end(JSON.stringify({ error: 'Missing photon query parameter' }));
-                return;
-            }
-            const photon = photons.find((p) => p.name === photonName);
-            if (!photon) {
-                res.writeHead(404);
-                res.end(JSON.stringify({ error: `Photon '${photonName}' not found` }));
-                return;
-            }
-            res.writeHead(200);
-            res.end(JSON.stringify({
-                mcpServers: {
-                    [`photon-${photonName}`]: {
-                        command: 'npx',
-                        args: ['-y', '@portel/photon', 'mcp', photonName],
+                    configurePhoton: async (photonName, config) => {
+                        return configurePhotonViaMCP(photonName, config, photons, photonMCPs, loader, savedConfig, workingDir, activeLoads);
                     },
-                },
-            }, null, 2));
-            return;
-        }
-        // OpenAPI Specification endpoint
-        // Serves auto-generated OpenAPI 3.1 spec from loaded photons
-        if (url.pathname === '/api/openapi.json') {
-            res.setHeader('Content-Type', 'application/json');
-            res.setHeader('Access-Control-Allow-Origin', '*');
-            try {
-                const serverUrl = `http://${req.headers.host || 'localhost:' + port}`;
-                const spec = generateOpenAPISpec(photons, serverUrl);
-                res.writeHead(200);
-                res.end(JSON.stringify(spec, null, 2));
-            }
-            catch (err) {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to generate OpenAPI spec' }));
-            }
-            return;
-        }
-        // Marketplace API: Search photons
-        if (url.pathname === '/api/marketplace/search') {
-            res.setHeader('Content-Type', 'application/json');
-            const query = url.searchParams.get('q') || '';
-            try {
-                const results = await marketplace.search(query);
-                const photonList = [];
-                for (const [name, sources] of results) {
-                    const source = sources[0]; // Use first source
-                    photonList.push({
-                        name,
-                        description: source.metadata?.description || '',
-                        version: source.metadata?.version || '',
-                        author: source.metadata?.author || '',
-                        tags: source.metadata?.tags || [],
-                        marketplace: source.marketplace.name,
-                        installed: photonMCPs.has(name),
-                    });
-                }
-                res.writeHead(200);
-                res.end(JSON.stringify({ photons: photonList }));
-            }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Search failed' }));
-            }
-            return;
-        }
-        // Marketplace API: List all available photons
-        if (url.pathname === '/api/marketplace/list') {
-            res.setHeader('Content-Type', 'application/json');
-            try {
-                // Auto-refresh caches older than 5 minutes so updates are detected without manual Sync
-                await marketplace.autoUpdateStaleCaches(5 * 60 * 1000);
-                const { readLocalMetadata } = await import('../marketplace-manager.js');
-                const allPhotons = await marketplace.getAllPhotons();
-                const localMetadata = await readLocalMetadata();
-                const photonList = [];
-                for (const [name, { metadata, marketplace: mp }] of allPhotons) {
-                    const installed = photonMCPs.has(name);
-                    let hasUpdate = false;
-                    let latestVersion = '';
-                    if (installed) {
-                        const installMeta = localMetadata.photons[`${name}.photon.ts`];
-                        if (installMeta && metadata.hash) {
-                            // Primary: hash comparison (catches code changes without version bump)
-                            hasUpdate = installMeta.originalHash !== metadata.hash;
+                    reloadPhoton: async (photonName) => {
+                        return reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, savedConfig, broadcastPhotonChange, activeLoads);
+                    },
+                    removePhoton: async (photonName) => {
+                        return removePhotonViaMCP(photonName, photons, photonMCPs, savedConfig, broadcastPhotonChange, workingDir);
+                    },
+                    updateMetadata: async (photonName, methodName, metadata) => {
+                        return updateMetadataViaMCP(photonName, methodName, metadata, photons);
+                    },
+                    generatePhotonHelp: async (photonName) => {
+                        return generatePhotonHelpMarkdown(photonName, photons);
+                    },
+                    loader, // Pass loader for proper execution context (this.emit() support)
+                    subscriptionManager, // For on-demand channel subscriptions
+                    broadcast: (message) => {
+                        const msg = message;
+                        // Forward JSON-RPC notifications (progress, status, etc.)
+                        if (msg.jsonrpc === '2.0' && msg.method) {
+                            broadcastNotification(msg.method, msg.params || {});
                         }
-                        else if (installMeta && metadata.version) {
-                            // Fallback: version comparison
-                            hasUpdate = installMeta.version !== metadata.version;
+                        // Forward channel events (task-moved, task-updated, etc.) with delta
+                        else if (msg.type === 'channel-event') {
+                            const params = {
+                                photon: msg.photon,
+                                channel: msg.channel,
+                                event: msg.event,
+                                data: msg.data,
+                            };
+                            // Buffer event for replay - find photonId from name for consistent channel key
+                            const photon = photons.find((p) => p.name === msg.photon);
+                            if (photon && msg.channel) {
+                                const [, itemId] = msg.channel.split(':');
+                                const bufferChannel = `${photon.id}:${itemId}`;
+                                const eventId = bufferEvent(bufferChannel, 'photon/channel-event', {
+                                    ...params,
+                                    photonId: photon.id,
+                                });
+                                broadcastToBeam('photon/channel-event', {
+                                    ...params,
+                                    photonId: photon.id,
+                                    _eventId: eventId,
+                                });
+                            }
+                            else {
+                                broadcastToBeam('photon/channel-event', params);
+                            }
                         }
-                        if (hasUpdate) {
-                            latestVersion = metadata.version || '';
+                        // Forward board-update for backwards compatibility
+                        else if (msg.type === 'board-update') {
+                            broadcastToBeam('photon/board-update', {
+                                photon: msg.photon,
+                                board: msg.board,
+                            });
                         }
-                    }
-                    photonList.push({
-                        name,
-                        description: metadata.description || '',
-                        version: metadata.version || '',
-                        author: metadata.author || '',
-                        tags: metadata.tags || [],
-                        marketplace: mp.name,
-                        icon: metadata.icon,
-                        internal: metadata.internal,
-                        installed,
-                        hasUpdate,
-                        latestVersion,
-                    });
-                }
-                res.writeHead(200);
-                res.end(JSON.stringify({ photons: photonList }));
+                    },
+                });
+                if (handled)
+                    return;
             }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to list photons' }));
+            // ══════════════════════════════════════════════════════════════════════════
+            // REST API routes (extracted modules)
+            // ══════════════════════════════════════════════════════════════════════════
+            if (url.pathname.startsWith('/api/')) {
+                if (await handleMarketplaceRoutes(req, res, url, beamState))
+                    return;
+                if (await handleBrowseRoutes(req, res, url, beamState))
+                    return;
+                if (await handleConfigRoutes(req, res, url, beamState))
+                    return;
             }
-            return;
-        }
-        // Marketplace API: Add/install a photon
-        if (url.pathname === '/api/marketplace/add' && req.method === 'POST') {
-            res.setHeader('Content-Type', 'application/json');
-            let body = '';
-            req.on('data', (chunk) => {
-                body += chunk;
-            });
-            req.on('end', async () => {
+            // Serve static frontend bundle
+            if (url.pathname === '/beam.bundle.js') {
                 try {
-                    const { name } = JSON.parse(body);
-                    if (!name) {
-                        res.writeHead(400);
-                        res.end(JSON.stringify({ error: 'Missing photon name' }));
-                        return;
-                    }
-                    // Fetch the photon from marketplace
-                    const result = await marketplace.fetchMCP(name);
-                    if (!result) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Photon '${name}' not found in marketplace` }));
-                        return;
-                    }
-                    // Write to working directory
-                    const targetPath = path.join(workingDir, `${name}.photon.ts`);
-                    await fs.writeFile(targetPath, result.content, 'utf-8');
-                    // Save metadata if available
-                    if (result.metadata) {
-                        const hash = (await import('../marketplace-manager.js')).calculateHash(result.content);
-                        await marketplace.savePhotonMetadata(`${name}.photon.ts`, result.marketplace, result.metadata, hash);
-                    }
-                    // Trigger immediate load so the photon appears in the sidebar right away
-                    // (don't wait for the file watcher which has debounce delay)
-                    handleFileChange(name);
-                    res.writeHead(200);
-                    res.end(JSON.stringify({
-                        success: true,
-                        name,
-                        path: targetPath,
-                        version: result.metadata?.version,
-                    }));
+                    const bundlePath = path.join(__dirname, '../../dist/beam.bundle.js');
+                    const content = await fs.readFile(bundlePath, 'utf-8');
+                    res.writeHead(200, { 'Content-Type': 'text/javascript' });
+                    res.end(content);
                 }
                 catch {
-                    res.writeHead(500);
-                    res.end(JSON.stringify({ error: 'Failed to add photon' }));
-                }
-            });
-            return;
-        }
-        // Marketplace API: Remove/uninstall a photon
-        if (url.pathname === '/api/marketplace/remove' && req.method === 'POST') {
-            res.setHeader('Content-Type', 'application/json');
-            const body = await readBody(req);
-            try {
-                const { name } = JSON.parse(body);
-                if (!name) {
-                    res.writeHead(400);
-                    res.end(JSON.stringify({ error: 'Missing photon name' }));
-                    return;
-                }
-                const filePath = path.join(workingDir, `${name}.photon.ts`);
-                if (!existsSync(filePath)) {
                     res.writeHead(404);
-                    res.end(JSON.stringify({ error: `Photon '${name}' not found` }));
-                    return;
-                }
-                // Remove the .photon.ts file
-                await fs.unlink(filePath);
-                // Remove UI assets directory if it exists
-                const assetsDir = path.join(workingDir, name);
-                if (existsSync(assetsDir) && lstatSync(assetsDir).isDirectory()) {
-                    await fs.rm(assetsDir, { recursive: true });
+                    res.end('Bundle not found. Run npm run build:beam first.');
                 }
-                // Clear compiled cache
-                const cacheDir = path.join(os.homedir(), '.cache', 'photon-mcp', 'compiled');
-                for (const ext of ['.js', '.js.map']) {
-                    try {
-                        await fs.unlink(path.join(cacheDir, `${name}${ext}`));
-                    }
-                    catch {
-                        /* ignore */
-                    }
-                }
-                // Remove from loaded photons
-                const idx = photons.findIndex((p) => p.name === name);
-                if (idx !== -1)
-                    photons.splice(idx, 1);
-                photonMCPs.delete(name);
-                res.writeHead(200);
-                res.end(JSON.stringify({ success: true, name }));
-                broadcastPhotonChange();
-            }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to remove photon' }));
-            }
-            return;
-        }
-        // Marketplace API: Get all marketplace sources
-        if (url.pathname === '/api/marketplace/sources') {
-            res.setHeader('Content-Type', 'application/json');
-            try {
-                const sources = marketplace.getAll();
-                const sourcesWithCounts = await Promise.all(sources.map(async (source) => {
-                    // Get photon count from cached manifest
-                    const manifest = await marketplace.getCachedManifest(source.name);
-                    return {
-                        name: source.name,
-                        repo: source.repo,
-                        source: source.source,
-                        sourceType: source.sourceType,
-                        enabled: source.enabled,
-                        photonCount: manifest?.photons?.length || 0,
-                        lastUpdated: source.lastUpdated,
-                    };
-                }));
-                res.writeHead(200);
-                res.end(JSON.stringify({ sources: sourcesWithCounts }));
-            }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to get marketplace sources' }));
+                return;
             }
-            return;
-        }
-        // Marketplace API: Add a new marketplace source
-        if (url.pathname === '/api/marketplace/sources/add' && req.method === 'POST') {
-            res.setHeader('Content-Type', 'application/json');
-            let body = '';
-            req.on('data', (chunk) => {
-                body += chunk;
-            });
-            req.on('end', async () => {
+            // Default route: Serve Lit App
+            if (url.pathname === '/' || !url.pathname.startsWith('/api')) {
                 try {
-                    const { source } = JSON.parse(body);
-                    if (!source) {
-                        res.writeHead(400);
-                        res.end(JSON.stringify({ error: 'Missing source parameter' }));
-                        return;
-                    }
-                    const result = await marketplace.add(source);
-                    // Update cache for the new marketplace
-                    if (result.added) {
-                        await marketplace.updateMarketplaceCache(result.marketplace.name);
-                    }
-                    res.writeHead(200);
-                    res.end(JSON.stringify({
-                        success: true,
-                        name: result.marketplace.name,
-                        added: result.added,
-                    }));
-                }
-                catch (err) {
-                    res.writeHead(400);
-                    res.end(JSON.stringify({ error: err.message }));
-                }
-            });
-            return;
-        }
-        // Marketplace API: Remove a marketplace source
-        if (url.pathname === '/api/marketplace/sources/remove' && req.method === 'POST') {
-            res.setHeader('Content-Type', 'application/json');
-            let body = '';
-            req.on('data', (chunk) => {
-                body += chunk;
-            });
-            req.on('end', async () => {
-                try {
-                    const { name } = JSON.parse(body);
-                    if (!name) {
-                        res.writeHead(400);
-                        res.end(JSON.stringify({ error: 'Missing name parameter' }));
-                        return;
-                    }
-                    const removed = await marketplace.remove(name);
-                    if (!removed) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Marketplace '${name}' not found` }));
-                        return;
-                    }
-                    res.writeHead(200);
-                    res.end(JSON.stringify({ success: true }));
-                }
-                catch (err) {
-                    res.writeHead(400);
-                    res.end(JSON.stringify({ error: err.message }));
-                }
-            });
-            return;
-        }
-        // Marketplace API: Toggle marketplace enabled/disabled
-        if (url.pathname === '/api/marketplace/sources/toggle' && req.method === 'POST') {
-            res.setHeader('Content-Type', 'application/json');
-            let body = '';
-            req.on('data', (chunk) => {
-                body += chunk;
-            });
-            req.on('end', async () => {
-                try {
-                    const { name, enabled } = JSON.parse(body);
-                    if (!name || typeof enabled !== 'boolean') {
-                        res.writeHead(400);
-                        res.end(JSON.stringify({ error: 'Missing name or enabled parameter' }));
-                        return;
-                    }
-                    const success = await marketplace.setEnabled(name, enabled);
-                    if (!success) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ error: `Marketplace '${name}' not found` }));
-                        return;
-                    }
-                    res.writeHead(200);
-                    res.end(JSON.stringify({ success: true }));
+                    const indexPath = path.join(__dirname, 'frontend/index.html');
+                    const content = await fs.readFile(indexPath, 'utf-8');
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(content);
                 }
                 catch (err) {
                     res.writeHead(500);
-                    res.end(JSON.stringify({ error: err.message }));
+                    res.end('Error serving UI: ' + String(err));
                 }
-            });
-            return;
-        }
-        // Marketplace API: Refresh marketplace cache
-        if (url.pathname === '/api/marketplace/refresh' && req.method === 'POST') {
-            res.setHeader('Content-Type', 'application/json');
-            let body = '';
-            req.on('data', (chunk) => {
-                body += chunk;
-            });
-            req.on('end', async () => {
-                try {
-                    const { name } = JSON.parse(body || '{}');
-                    if (name) {
-                        // Refresh specific marketplace
-                        const success = await marketplace.updateMarketplaceCache(name);
-                        res.writeHead(200);
-                        res.end(JSON.stringify({ success, updated: success ? [name] : [] }));
-                    }
-                    else {
-                        // Refresh all enabled marketplaces
-                        const results = await marketplace.updateAllCaches();
-                        const updated = Array.from(results.entries())
-                            .filter(([, success]) => success)
-                            .map(([name]) => name);
-                        res.writeHead(200);
-                        res.end(JSON.stringify({ success: true, updated }));
-                    }
-                }
-                catch (err) {
-                    res.writeHead(500);
-                    res.end(JSON.stringify({ error: err.message }));
-                }
-            });
-            return;
-        }
-        // Marketplace API: Check for available updates
-        if (url.pathname === '/api/marketplace/updates') {
-            res.setHeader('Content-Type', 'application/json');
-            try {
-                const { readLocalMetadata } = await import('../marketplace-manager.js');
-                const localMetadata = await readLocalMetadata();
-                const updates = [];
-                // Check each installed photon for updates (hash-based primary, version fallback)
-                for (const [fileName, installMeta] of Object.entries(localMetadata.photons)) {
-                    const photonName = fileName.replace(/\.photon\.ts$/, '');
-                    const latestInfo = await marketplace.getPhotonMetadata(photonName);
-                    if (latestInfo) {
-                        const hashChanged = latestInfo.metadata.hash
-                            ? installMeta.originalHash !== latestInfo.metadata.hash
-                            : false;
-                        const versionChanged = latestInfo.metadata.version !== installMeta.version;
-                        if (hashChanged || versionChanged) {
-                            updates.push({
-                                name: photonName,
-                                fileName,
-                                currentVersion: installMeta.version,
-                                latestVersion: latestInfo.metadata.version,
-                                marketplace: latestInfo.marketplace.name,
-                            });
-                        }
-                    }
-                }
-                res.writeHead(200);
-                res.end(JSON.stringify({ updates }));
-            }
-            catch {
-                res.writeHead(500);
-                res.end(JSON.stringify({ error: 'Failed to check for updates' }));
+                return;
             }
-            return;
-        }
-        // Test API: Run a single test
-        // Supports modes: 'direct' (call instance method), 'mcp' (call via executeTool), 'cli' (spawn subprocess)
-        if (url.pathname === '/api/test/run' && req.method === 'POST') {
-            let body = '';
-            req.on('data', (chunk) => (body += chunk));
-            req.on('end', async () => {
-                res.setHeader('Content-Type', 'application/json');
-                try {
-                    const { photon: photonName, test: testName, mode = 'direct' } = JSON.parse(body);
-                    // Find the photon
-                    const photon = photons.find((p) => p.name === photonName);
-                    if (!photon) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ passed: false, error: 'Photon not found', mode }));
-                        return;
-                    }
-                    // Get the MCP instance
-                    const mcp = photonMCPs.get(photonName);
-                    if (!mcp || !mcp.instance) {
-                        res.writeHead(404);
-                        res.end(JSON.stringify({ passed: false, error: 'Photon not loaded', mode }));
-                        return;
-                    }
-                    // Run the test method
-                    const start = Date.now();
-                    try {
-                        let result;
-                        if (mode === 'mcp') {
-                            // MCP mode: use executeTool to simulate MCP protocol
-                            // This tests the full tool execution path
-                            result = await loader.executeTool(mcp, testName, {}, {});
-                        }
-                        else if (mode === 'cli') {
-                            // CLI mode: spawn subprocess to test CLI interface
-                            const cliPath = path.resolve(__dirname, '..', 'cli.js');
-                            const args = ['cli', photonName, testName, '--json', '--dir', workingDir];
-                            result = await new Promise((resolve) => {
-                                const proc = spawn('node', [cliPath, ...args], {
-                                    cwd: workingDir,
-                                    timeout: 30000,
-                                    env: { ...process.env },
-                                });
-                                let stdout = '';
-                                let stderr = '';
-                                proc.stdout.on('data', (data) => (stdout += data.toString()));
-                                proc.stderr.on('data', (data) => (stderr += data.toString()));
-                                proc.on('close', (code) => {
-                                    const output = stdout.trim() || stderr.trim();
-                                    const hasOutput = output.length > 0;
-                                    const infraErrors = [
-                                        'Photon not found',
-                                        'command not found',
-                                        'Cannot find module',
-                                        'ENOENT',
-                                    ];
-                                    const isInfraError = infraErrors.some((e) => (stdout + stderr).includes(e));
-                                    if (hasOutput && !isInfraError) {
-                                        // CLI interface worked - transport successful
-                                        resolve({ passed: true, message: 'CLI interface test passed' });
-                                    }
-                                    else if (isInfraError) {
-                                        resolve({ passed: false, error: `CLI infrastructure error: ${output}` });
-                                    }
-                                    else {
-                                        resolve({
-                                            passed: false,
-                                            error: `CLI test failed with code ${code}: no output`,
-                                        });
-                                    }
-                                });
-                                proc.on('error', (err) => {
-                                    resolve({ passed: false, error: `CLI spawn error: ${err.message}` });
-                                });
-                            });
-                        }
-                        else {
-                            // Direct mode: call instance method directly
-                            result = await mcp.instance[testName]();
-                        }
-                        const duration = Date.now() - start;
-                        // Check result
-                        if (result && typeof result === 'object') {
-                            if (result.skipped === true) {
-                                res.writeHead(200);
-                                res.end(JSON.stringify({
-                                    passed: true,
-                                    skipped: true,
-                                    message: result.reason || 'Skipped',
-                                    duration,
-                                    mode,
-                                }));
-                            }
-                            else if (result.passed === false) {
-                                res.writeHead(200);
-                                res.end(JSON.stringify({
-                                    passed: false,
-                                    error: result.error || result.message || 'Test failed',
-                                    duration,
-                                    mode,
-                                }));
-                            }
-                            else {
-                                res.writeHead(200);
-                                res.end(JSON.stringify({
-                                    passed: true,
-                                    message: result?.message,
-                                    duration,
-                                    mode,
-                                }));
-                            }
-                        }
-                        else {
-                            res.writeHead(200);
-                            res.end(JSON.stringify({
-                                passed: true,
-                                duration,
-                                mode,
-                            }));
-                        }
-                    }
-                    catch (testError) {
-                        const duration = Date.now() - start;
-                        res.writeHead(200);
-                        res.end(JSON.stringify({
-                            passed: false,
-                            error: testError.message || String(testError),
-                            duration,
-                            mode,
-                        }));
-                    }
-                }
-                catch {
-                    res.writeHead(400);
-                    res.end(JSON.stringify({ passed: false, error: 'Invalid request' }));
-                }
-            });
-            return;
-        }
-        res.writeHead(404);
-        res.end('Not Found');
+            res.writeHead(404);
+            res.end('Not Found');
+        })();
     });
     // Broadcast photon changes to all connected clients via MCP SSE
     const broadcastPhotonChange = () => {
@@ -2324,6 +578,69 @@ export async function startBeam(rawWorkingDir, port) {
     // File watcher for hot reload
     const watchers = [];
     const pendingReloads = new Map();
+    const activeLoads = new Set(); // Photons currently being loaded (prevents concurrent duplicate loads)
+    const pendingAfterLoad = new Set(); // File changes that arrived while a load was active; re-triggered after
+    const symlinkWatchedDirs = new Set(); // Track which source dirs already have watchers (prevents duplicates on re-setup)
+    // Set up file watchers for a symlinked photon's real source directory and asset folder.
+    // Called both at startup and after a previously-errored symlinked photon recovers.
+    const setupSymlinkWatcher = (photonName, photonPath) => {
+        try {
+            const stat = lstatSync(photonPath);
+            if (!stat.isSymbolicLink())
+                return;
+            const realPath = realpathSync(photonPath);
+            const realDir = path.dirname(realPath);
+            // Skip if we already have a watcher on this source directory for this photon
+            const watchKey = `${photonName}:${realDir}`;
+            if (symlinkWatchedDirs.has(watchKey))
+                return;
+            const realFileName = path.basename(realPath);
+            try {
+                const srcDirWatcher = watch(realDir, (eventType, filename) => {
+                    if (filename === realFileName) {
+                        void handleFileChange(photonName);
+                    }
+                });
+                srcDirWatcher.on('error', () => { });
+                watchers.push(srcDirWatcher);
+                symlinkWatchedDirs.add(watchKey);
+            }
+            catch {
+                // Source file watching not available
+            }
+            // Watch asset folder if it exists
+            const assetFolder = path.join(realDir, photonName);
+            if (existsSync(assetFolder)) {
+                try {
+                    const assetWatcher = watch(assetFolder, { recursive: true }, (eventType, filename) => {
+                        if (filename) {
+                            if (filename.endsWith('.json') ||
+                                filename.startsWith('boards/') ||
+                                filename === 'data.json') {
+                                return;
+                            }
+                            logger.info(`📁 Asset change detected: ${photonName}/${filename}`);
+                            void handleFileChange(photonName);
+                        }
+                    });
+                    assetWatcher.on('error', (err) => {
+                        logger.warn(`Watcher error for ${photonName}/: ${err.message}`);
+                    });
+                    watchers.push(assetWatcher);
+                }
+                catch {
+                    // Asset watching not available
+                }
+            }
+            logger.info(existsSync(assetFolder)
+                ? `👀 Watching ${photonName}/ (symlinked → ${assetFolder})`
+                : `👀 Watching ${photonName} (symlinked → ${realDir})`);
+        }
+        catch {
+            // Symlink broken or unreadable — will retry on next successful reload
+            logger.debug(`⏭️ Symlink watcher deferred for ${photonName}: target not resolvable`);
+        }
+    };
     // Determine which photon a file change belongs to
     const getPhotonForPath = (changedPath) => {
         const relativePath = path.relative(workingDir, changedPath);
@@ -2350,234 +667,318 @@ export async function startBeam(rawWorkingDir, port) {
         if (pending)
             clearTimeout(pending);
         // Debounce - wait 100ms for batch saves
-        pendingReloads.set(photonName, setTimeout(async () => {
-            pendingReloads.delete(photonName);
-            const photonIndex = photons.findIndex((p) => p.name === photonName);
-            const isNewPhoton = photonIndex === -1;
-            const photonPath = isNewPhoton
-                ? path.join(workingDir, `${photonName}.photon.ts`)
-                : photons[photonIndex].path;
-            // Handle file deletion - if file no longer exists and photon is in list, remove it
-            if (!isNewPhoton && photonPath && !existsSync(photonPath)) {
-                logger.info(`🗑️ Photon file deleted: ${photonName}`);
-                photons.splice(photonIndex, 1);
-                photonMCPs.delete(photonName);
-                // Also remove from saved config
-                if (savedConfig.photons[photonName]) {
-                    delete savedConfig.photons[photonName];
-                    await saveConfig(savedConfig);
+        pendingReloads.set(photonName, setTimeout(() => {
+            void (async () => {
+                pendingReloads.delete(photonName);
+                // Skip if already loading this photon — but mark it so we re-run after the active load
+                // finishes. Without this, file changes that arrive mid-load are silently dropped.
+                if (activeLoads.has(photonName)) {
+                    pendingAfterLoad.add(photonName);
+                    return;
                 }
-                broadcastPhotonChange();
-                broadcastToBeam('beam/photon-removed', { name: photonName });
-                return;
-            }
-            logger.info(isNewPhoton
-                ? `✨ New photon detected: ${photonName}`
-                : `🔄 File change detected, reloading ${photonName}...`);
-            // Auto-scaffold empty photon files with a starter template
-            if (isNewPhoton) {
+                activeLoads.add(photonName);
                 try {
-                    const rawContent = await fs.readFile(photonPath, 'utf-8');
-                    if (rawContent.trim().length === 0) {
-                        const className = photonName
-                            .split(/[-_]/)
-                            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-                            .join('');
-                        const scaffold = `/**\n * ${className} Photon\n */\n\nexport default class ${className} {\n  /**\n   * Example tool\n   * @param message Message to echo\n   */\n  async echo(params: { message: string }) {\n    return \`Echo: \${params.message}\`;\n  }\n}\n`;
-                        await fs.writeFile(photonPath, scaffold, 'utf-8');
-                        logger.info(`📝 Scaffolded empty file: ${photonName}.photon.ts`);
-                        // The write triggers another watcher event which will load the scaffolded photon
+                    const photonIndex = photons.findIndex((p) => p.name === photonName);
+                    const isNewPhoton = photonIndex === -1;
+                    const photonPath = isNewPhoton
+                        ? path.join(workingDir, `${photonName}.photon.ts`)
+                        : photons[photonIndex].path;
+                    const previouslyConfigured = !isNewPhoton && photons[photonIndex]?.configured === true;
+                    // Handle file deletion - if file no longer exists and photon is in list, remove it
+                    if (!isNewPhoton && photonPath && !existsSync(photonPath)) {
+                        // For symlinks, `ln -sf` causes a transient gap between unlink and create.
+                        // Retry once after a short delay before treating it as a real deletion.
+                        let isTransientSymlinkReplacement = false;
+                        try {
+                            const stat = lstatSync(photonPath);
+                            if (stat.isSymbolicLink()) {
+                                await new Promise((r) => setTimeout(r, 200));
+                                if (existsSync(photonPath)) {
+                                    isTransientSymlinkReplacement = true;
+                                }
+                            }
+                        }
+                        catch {
+                            // lstat failed — symlink inode itself is gone, proceed with removal
+                        }
+                        if (isTransientSymlinkReplacement) {
+                            logger.info(`🔗 Symlink replaced: ${photonName}, treating as change`);
+                            // Fall through to reload logic below
+                        }
+                        else {
+                            logger.info(`🗑️ Photon file deleted: ${photonName}`);
+                            photons.splice(photonIndex, 1);
+                            photonMCPs.delete(photonName);
+                            // Also remove from saved config
+                            if (savedConfig.photons[photonName]) {
+                                delete savedConfig.photons[photonName];
+                                await saveConfig(savedConfig, workingDir);
+                            }
+                            broadcastPhotonChange();
+                            broadcastToBeam('beam/photon-removed', { name: photonName });
+                            return;
+                        }
+                    }
+                    // Ghost event: watcher fired for a new photon but the file doesn't exist.
+                    // This happens on macOS FSEvents spurious events or create-then-delete races.
+                    // Nothing to load — ignore silently.
+                    if (isNewPhoton && !existsSync(photonPath)) {
+                        logger.debug(`👻 Ghost event for ${photonName}: file not found, skipping`);
                         return;
                     }
-                }
-                catch {
-                    // File read failed, continue with normal load attempt
-                }
-            }
-            // For new photons, check if configuration is needed first
-            if (isNewPhoton) {
-                const extractor = new SchemaExtractor();
-                let constructorParams = [];
-                try {
-                    const source = await fs.readFile(photonPath, 'utf-8');
-                    const params = extractor.extractConstructorParams(source);
-                    constructorParams = params
-                        .filter((p) => p.isPrimitive)
-                        .map((p) => ({
-                        name: p.name,
-                        envVar: toEnvVarName(photonName, p.name),
-                        type: p.type,
-                        isOptional: p.isOptional,
-                        hasDefault: p.hasDefault,
-                        defaultValue: p.defaultValue,
-                    }));
-                }
-                catch {
-                    // Can't extract params, try to load anyway
-                }
-                // Check if any required params are missing
-                const missingRequired = constructorParams.filter((p) => !p.isOptional && !p.hasDefault && !process.env[p.envVar]);
-                if (missingRequired.length > 0 && constructorParams.length > 0) {
-                    // Add as unconfigured photon
-                    const targetPhoton = {
-                        id: generatePhotonId(photonPath),
-                        name: photonName,
-                        path: photonPath,
-                        configured: false,
-                        requiredParams: constructorParams,
-                        errorReason: 'missing-config',
-                        errorMessage: `Missing required: ${missingRequired.map((p) => p.name).join(', ')}`,
-                    };
-                    photons.push(targetPhoton);
-                    broadcastPhotonChange();
-                    logger.info(`⚙️ ${photonName} added (needs configuration)`);
-                    return;
-                }
-            }
-            try {
-                // Load or reload the photon
-                const mcp = isNewPhoton
-                    ? await loader.loadFile(photonPath)
-                    : await loader.reloadFile(photonPath);
-                if (!mcp.instance)
-                    throw new Error('Failed to create instance');
-                photonMCPs.set(photonName, mcp);
-                // Re-extract schema - use extractAllFromSource to get both tools and templates
-                const extractor = new SchemaExtractor();
-                const reloadSource = await fs.readFile(photonPath, 'utf-8');
-                const { tools: schemas, templates } = extractor.extractAllFromSource(reloadSource);
-                mcp.schemas = schemas; // Store schemas for result rendering
-                const lifecycleMethods = ['onInitialize', 'onShutdown', 'constructor'];
-                const uiAssets = mcp.assets?.ui || [];
-                const methods = schemas
-                    .filter((schema) => !lifecycleMethods.includes(schema.name))
-                    .map((schema) => {
-                    const linkedAsset = uiAssets.find((ui) => ui.linkedTool === schema.name);
-                    return {
-                        name: schema.name,
-                        description: schema.description || '',
-                        params: schema.inputSchema || { type: 'object', properties: {}, required: [] },
-                        returns: { type: 'object' },
-                        autorun: schema.autorun || false,
-                        outputFormat: schema.outputFormat,
-                        layoutHints: schema.layoutHints,
-                        buttonLabel: schema.buttonLabel,
-                        icon: schema.icon,
-                        linkedUi: linkedAsset?.id,
-                    };
-                });
-                // Add templates as methods
-                templates.forEach((template) => {
-                    if (!lifecycleMethods.includes(template.name)) {
-                        methods.push({
-                            name: template.name,
-                            description: template.description || '',
-                            params: template.inputSchema || { type: 'object', properties: {}, required: [] },
-                            returns: { type: 'object' },
-                            isTemplate: true,
-                            outputFormat: 'markdown',
-                        });
+                    logger.info(isNewPhoton
+                        ? `✨ New photon detected: ${photonName}`
+                        : `🔄 File change detected, reloading ${photonName}...`);
+                    // Auto-scaffold empty photon files with a starter template
+                    if (isNewPhoton) {
+                        try {
+                            const rawContent = await fs.readFile(photonPath, 'utf-8');
+                            if (rawContent.trim().length === 0) {
+                                const className = photonName
+                                    .split(/[-_]/)
+                                    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                                    .join('');
+                                const scaffold = `/**\n * ${className} Photon\n */\n\nexport default class ${className} {\n  /**\n   * Example tool\n   * @param message Message to echo\n   */\n  async echo(params: { message: string }) {\n    return \`Echo: \${params.message}\`;\n  }\n}\n`;
+                                await fs.writeFile(photonPath, scaffold, 'utf-8');
+                                logger.info(`📝 Scaffolded empty file: ${photonName}.photon.ts`);
+                                // The write triggers another watcher event which will load the scaffolded photon
+                                return;
+                            }
+                        }
+                        catch {
+                            // File read failed, continue with normal load attempt
+                        }
+                    }
+                    // For new photons, check if configuration is needed first
+                    if (isNewPhoton) {
+                        const extractor = new SchemaExtractor();
+                        let constructorParams = [];
+                        try {
+                            const source = await fs.readFile(photonPath, 'utf-8');
+                            const params = extractor.extractConstructorParams(source);
+                            constructorParams = params
+                                .filter((p) => p.isPrimitive)
+                                .map((p) => ({
+                                name: p.name,
+                                envVar: toEnvVarName(photonName, p.name),
+                                type: p.type,
+                                isOptional: p.isOptional,
+                                hasDefault: p.hasDefault,
+                                defaultValue: p.defaultValue,
+                            }));
+                        }
+                        catch {
+                            // Can't extract params, try to load anyway
+                        }
+                        // Check if any required params are missing
+                        const missingRequired = constructorParams.filter((p) => !p.isOptional && !p.hasDefault && !process.env[p.envVar]);
+                        if (missingRequired.length > 0 && constructorParams.length > 0) {
+                            // Add as unconfigured photon
+                            const targetPhoton = {
+                                id: generatePhotonId(photonPath),
+                                name: photonName,
+                                path: photonPath,
+                                configured: false,
+                                requiredParams: constructorParams,
+                                errorReason: 'missing-config',
+                                errorMessage: `Missing required: ${missingRequired.map((p) => p.name).join(', ')}`,
+                            };
+                            if (!photons.find((p) => p.name === photonName)) {
+                                photons.push(targetPhoton);
+                                broadcastPhotonChange();
+                                logger.info(`⚙️ ${photonName} added (needs configuration)`);
+                            }
+                            return;
+                        }
                     }
-                });
-                // Apply @visibility annotations
-                applyMethodVisibility(reloadSource, methods);
-                // Check if this is an App (has main() method with @ui)
-                const mainMethod = methods.find((m) => m.name === 'main' && m.linkedUi);
-                // Extract class metadata from source
-                const reloadClassMeta = extractClassMetadataFromSource(reloadSource);
-                // Extract constructor params for reconfiguration support
-                let reloadConstructorParams = [];
-                try {
-                    const reloadParams = extractor.extractConstructorParams(reloadSource);
-                    reloadConstructorParams = reloadParams
-                        .filter((p) => p.isPrimitive)
-                        .map((p) => ({
-                        name: p.name,
-                        envVar: toEnvVarName(photonName, p.name),
-                        type: p.type,
-                        isOptional: p.isOptional,
-                        hasDefault: p.hasDefault,
-                        defaultValue: p.defaultValue,
-                    }));
-                }
-                catch {
-                    // Can't extract params
-                }
-                backfillEnvDefaults(mcp.instance, reloadConstructorParams);
-                const isStateful = /@stateful\b/.test(reloadSource);
-                const reloadedPhoton = {
-                    id: generatePhotonId(photonPath),
-                    name: photonName,
-                    path: photonPath,
-                    configured: true,
-                    methods,
-                    isApp: !!mainMethod,
-                    appEntry: mainMethod,
-                    description: reloadClassMeta.description,
-                    icon: reloadClassMeta.icon,
-                    internal: reloadClassMeta.internal,
-                    ...(isStateful && { stateful: true }),
-                    ...(reloadConstructorParams.length > 0 && { requiredParams: reloadConstructorParams }),
-                    ...(mcp.injectedPhotons &&
-                        mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
-                };
-                if (isNewPhoton) {
-                    photons.push(reloadedPhoton);
-                    broadcastPhotonChange();
-                    logger.info(`✅ ${photonName} added`);
-                }
-                else {
-                    photons[photonIndex] = reloadedPhoton;
-                    logger.info(`📡 Broadcasting hot-reload for ${photonName}`);
-                    broadcastToBeam('beam/hot-reload', { photon: reloadedPhoton });
-                    broadcastPhotonChange();
-                    logger.info(`✅ ${photonName} hot reloaded`);
-                }
-            }
-            catch (error) {
-                const errorMsg = error instanceof Error ? error.message : String(error);
-                // For new photons that fail to load, add as unconfigured
-                if (isNewPhoton) {
-                    const extractor = new SchemaExtractor();
-                    let constructorParams = [];
                     try {
-                        const source = await fs.readFile(photonPath, 'utf-8');
-                        const params = extractor.extractConstructorParams(source);
-                        constructorParams = params
-                            .filter((p) => p.isPrimitive)
-                            .map((p) => ({
-                            name: p.name,
-                            envVar: toEnvVarName(photonName, p.name),
-                            type: p.type,
-                            isOptional: p.isOptional,
-                            hasDefault: p.hasDefault,
-                            defaultValue: p.defaultValue,
-                        }));
+                        // Load or reload the photon
+                        const mcp = isNewPhoton
+                            ? await loader.loadFile(photonPath)
+                            : await loader.reloadFile(photonPath);
+                        if (!mcp.instance)
+                            throw new Error('Failed to create instance');
+                        photonMCPs.set(photonName, mcp);
+                        // Re-extract schema - use extractAllFromSource to get both tools and templates
+                        const extractor = new SchemaExtractor();
+                        const reloadSource = await fs.readFile(photonPath, 'utf-8');
+                        const { tools: schemas, templates } = extractor.extractAllFromSource(reloadSource);
+                        mcp.schemas = schemas; // Store schemas for result rendering
+                        const lifecycleMethods = ['onInitialize', 'onShutdown', 'constructor'];
+                        const uiAssets = mcp.assets?.ui || [];
+                        const methods = schemas
+                            .filter((schema) => !lifecycleMethods.includes(schema.name))
+                            .map((schema) => {
+                            const linkedAsset = uiAssets.find((ui) => ui.linkedTool === schema.name);
+                            return {
+                                name: schema.name,
+                                description: schema.description || '',
+                                params: schema.inputSchema || { type: 'object', properties: {}, required: [] },
+                                returns: { type: 'object' },
+                                autorun: schema.autorun || false,
+                                outputFormat: schema.outputFormat,
+                                layoutHints: schema.layoutHints,
+                                buttonLabel: schema.buttonLabel,
+                                icon: schema.icon,
+                                linkedUi: linkedAsset?.id,
+                            };
+                        });
+                        // Add templates as methods
+                        templates.forEach((template) => {
+                            if (!lifecycleMethods.includes(template.name)) {
+                                methods.push({
+                                    name: template.name,
+                                    description: template.description || '',
+                                    params: template.inputSchema || {
+                                        type: 'object',
+                                        properties: {},
+                                        required: [],
+                                    },
+                                    returns: { type: 'object' },
+                                    isTemplate: true,
+                                    outputFormat: 'markdown',
+                                });
+                            }
+                        });
+                        // Add auto-generated settings tool if the photon has `protected settings`
+                        if (mcp.settingsSchema?.hasSettings) {
+                            const settingsTool = mcp.tools.find((t) => t.name === 'settings');
+                            if (settingsTool) {
+                                methods.push({
+                                    name: 'settings',
+                                    description: settingsTool.description || 'Board settings',
+                                    params: settingsTool.inputSchema || { type: 'object', properties: {} },
+                                    returns: { type: 'object' },
+                                });
+                            }
+                        }
+                        // Apply @visibility annotations
+                        applyMethodVisibility(reloadSource, methods);
+                        // Check if this is an App (has main() method with @ui)
+                        const mainMethod = methods.find((m) => m.name === 'main' && m.linkedUi);
+                        // Extract class metadata from source
+                        const reloadClassMeta = extractClassMetadataFromSource(reloadSource);
+                        // Extract constructor params for reconfiguration support
+                        let reloadConstructorParams = [];
+                        try {
+                            const reloadParams = extractor.extractConstructorParams(reloadSource);
+                            reloadConstructorParams = reloadParams
+                                .filter((p) => p.isPrimitive)
+                                .map((p) => ({
+                                name: p.name,
+                                envVar: toEnvVarName(photonName, p.name),
+                                type: p.type,
+                                isOptional: p.isOptional,
+                                hasDefault: p.hasDefault,
+                                defaultValue: p.defaultValue,
+                            }));
+                        }
+                        catch {
+                            // Can't extract params
+                        }
+                        backfillEnvDefaults(mcp.instance, reloadConstructorParams);
+                        const isStateful = /@stateful\b/.test(reloadSource);
+                        const reloadedPhoton = {
+                            id: generatePhotonId(photonPath),
+                            name: photonName,
+                            path: photonPath,
+                            configured: true,
+                            methods,
+                            isApp: !!mainMethod,
+                            appEntry: mainMethod,
+                            description: reloadClassMeta.description,
+                            icon: reloadClassMeta.icon,
+                            internal: reloadClassMeta.internal,
+                            ...(isStateful && { stateful: true }),
+                            ...(mcp.settingsSchema?.hasSettings && { hasSettings: true }),
+                            ...(reloadConstructorParams.length > 0 && {
+                                requiredParams: reloadConstructorParams,
+                            }),
+                            ...(mcp.injectedPhotons &&
+                                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
+                        };
+                        // Re-find the index — it may have shifted during the async work above
+                        const currentIndex = photons.findIndex((p) => p.name === photonName);
+                        if (isNewPhoton) {
+                            if (currentIndex === -1) {
+                                photons.push(reloadedPhoton);
+                                broadcastPhotonChange();
+                                logger.info(`✅ ${photonName} added`);
+                            }
+                            // else: another async path already added it — skip duplicate push
+                        }
+                        else {
+                            if (currentIndex !== -1) {
+                                photons[currentIndex] = reloadedPhoton;
+                                logger.info(`📡 Broadcasting hot-reload for ${photonName}`);
+                                broadcastToBeam('beam/hot-reload', { photon: reloadedPhoton });
+                                broadcastPhotonChange();
+                                logger.info(`✅ ${photonName} hot reloaded`);
+                            }
+                            // else: photon was removed while we were reloading — discard result
+                        }
+                        // If this photon is symlinked and was previously errored (or new), set up
+                        // source-directory watchers that may have been skipped at startup.
+                        if (isNewPhoton || !previouslyConfigured) {
+                            setupSymlinkWatcher(photonName, reloadedPhoton.path);
+                        }
                     }
-                    catch {
-                        // Ignore extraction errors
+                    catch (error) {
+                        const errorMsg = error instanceof Error ? error.message : String(error);
+                        // For new photons that fail to load, add as unconfigured
+                        if (isNewPhoton) {
+                            const extractor = new SchemaExtractor();
+                            let constructorParams = [];
+                            try {
+                                const source = await fs.readFile(photonPath, 'utf-8');
+                                const params = extractor.extractConstructorParams(source);
+                                constructorParams = params
+                                    .filter((p) => p.isPrimitive)
+                                    .map((p) => ({
+                                    name: p.name,
+                                    envVar: toEnvVarName(photonName, p.name),
+                                    type: p.type,
+                                    isOptional: p.isOptional,
+                                    hasDefault: p.hasDefault,
+                                    defaultValue: p.defaultValue,
+                                }));
+                            }
+                            catch {
+                                // Ignore extraction errors
+                            }
+                            const targetPhoton = {
+                                id: generatePhotonId(photonPath),
+                                name: photonName,
+                                path: photonPath,
+                                configured: false,
+                                requiredParams: constructorParams,
+                                errorReason: constructorParams.length > 0 ? 'missing-config' : 'load-error',
+                                errorMessage: errorMsg.slice(0, 200),
+                            };
+                            if (!photons.find((p) => p.name === photonName)) {
+                                photons.push(targetPhoton);
+                                broadcastPhotonChange();
+                                logger.info(`⚙️ ${photonName} added (needs attention: ${targetPhoton.errorReason})`);
+                            }
+                            return;
+                        }
+                        logger.error(`Hot reload failed for ${photonName}: ${errorMsg}`);
+                        broadcastToBeam('beam/error', {
+                            type: 'hot-reload-error',
+                            photon: photonName,
+                            message: errorMsg.slice(0, 200),
+                        });
                     }
-                    const targetPhoton = {
-                        id: generatePhotonId(photonPath),
-                        name: photonName,
-                        path: photonPath,
-                        configured: false,
-                        requiredParams: constructorParams,
-                        errorReason: constructorParams.length > 0 ? 'missing-config' : 'load-error',
-                        errorMessage: errorMsg.slice(0, 200),
-                    };
-                    photons.push(targetPhoton);
-                    broadcastPhotonChange();
-                    logger.info(`⚙️ ${photonName} added (needs attention: ${targetPhoton.errorReason})`);
-                    return;
                 }
-                logger.error(`Hot reload failed for ${photonName}: ${errorMsg}`);
-                broadcastToBeam('beam/error', {
-                    type: 'hot-reload-error',
-                    photon: photonName,
-                    message: errorMsg.slice(0, 200),
-                });
-            }
+                finally {
+                    activeLoads.delete(photonName);
+                    // If another file change arrived while we were loading, process it now
+                    if (pendingAfterLoad.has(photonName)) {
+                        pendingAfterLoad.delete(photonName);
+                        void handleFileChange(photonName);
+                    }
+                }
+            })();
         }, 100));
     };
     // Watch working directory recursively
@@ -2590,7 +991,7 @@ export async function startBeam(rawWorkingDir, port) {
             const photonName = getPhotonForPath(fullPath);
             if (photonName) {
                 logger.info(`📁 Change detected: ${filename} → ${photonName}`);
-                handleFileChange(photonName);
+                void handleFileChange(photonName);
             }
         });
         // Handle watcher errors (e.g., EMFILE: too many open files)
@@ -2607,7 +1008,7 @@ export async function startBeam(rawWorkingDir, port) {
         logger.info(`👀 Watching for changes in ${workingDir}`);
     }
     catch (error) {
-        logger.warn(`File watching not available: ${error}`);
+        logger.warn(`File watching not available: ${String(error)}`);
     }
     // Symlinked and bundled photon watchers are set up after photon loading (see below)
     // Bind to 0.0.0.0 for tunnel access, with port fallback
@@ -2636,7 +1037,6 @@ export async function startBeam(rawWorkingDir, port) {
         });
     };
     // Find an available port (compact status line output)
-    const isTTY = process.stderr.isTTY;
     while (currentPort < port + maxPortAttempts) {
         const available = await isPortAvailable(currentPort);
         if (available) {
@@ -2689,7 +1089,7 @@ export async function startBeam(rawWorkingDir, port) {
                 const url = `http://localhost:${currentPort}`;
                 if (isTTY)
                     process.stderr.write('\r\x1b[K'); // Clear any port status line
-                console.log(`⚡ Photon Beam → ${url} (loading photons...)\n`);
+                startup.showUrl(url); // Show URL status line (not ready yet)
                 resolve();
             });
             // Configure server and socket timeouts to prevent premature disconnections
@@ -2710,7 +1110,10 @@ export async function startBeam(rawWorkingDir, port) {
         const results = await Promise.allSettled(batch.map((name) => loadSinglePhoton(name)));
         for (const result of results) {
             if (result.status === 'fulfilled' && result.value) {
-                photons.push(result.value);
+                // Dedup: file watcher may have already loaded this photon during startup
+                if (!photons.find((p) => p.name === result.value.name)) {
+                    photons.push(result.value);
+                }
             }
         }
     }
@@ -2725,7 +1128,9 @@ export async function startBeam(rawWorkingDir, port) {
         ? `${configuredCount} ready, ${unconfiguredCount} need setup`
         : `${configuredCount} photon${configuredCount !== 1 ? 's' : ''} ready`;
     const mcpStatus = externalMCPList.length > 0 ? `, ${connectedMCPs}/${externalMCPList.length} MCPs` : '';
-    console.log(`⚡ Photon Beam ready (${photonStatus}${mcpStatus})`);
+    const url = `http://localhost:${process.env.BEAM_PORT || port}`;
+    // Mark startup complete — flushes queued output and restores console
+    startup.ready();
     // Notify connected clients that photon list is now available
     broadcastPhotonChange();
     // Auto-start daemon and subscribe to state-changed events for stateful photons
@@ -2745,7 +1150,8 @@ export async function startBeam(rawWorkingDir, port) {
                     });
                 }, {
                     reconnect: true,
-                    onReconnect: () => logger.info(`📡 Reconnected ${channel} subscription`),
+                    workingDir,
+                    onReconnect: () => logger.debug(`📡 Reconnected ${channel} subscription`),
                     onRefreshNeeded: () => {
                         logger.info(`📡 Refresh needed for ${channel} (events lost during daemon restart)`);
                         broadcastToBeam('photon/state-changed', {
@@ -2776,38 +1182,50 @@ export async function startBeam(rawWorkingDir, port) {
         try {
             const stat = lstatSync(photon.path);
             if (stat.isSymbolicLink()) {
-                const realPath = realpathSync(photon.path);
-                const realDir = path.dirname(realPath);
-                const assetFolder = path.join(realDir, photon.name);
-                if (existsSync(assetFolder)) {
-                    const assetWatcher = watch(assetFolder, { recursive: true }, (eventType, filename) => {
-                        if (filename) {
-                            if (filename.endsWith('.json') ||
-                                filename.startsWith('boards/') ||
-                                filename === 'data.json') {
-                                logger.debug(`⏭️ Ignoring data file change: ${photon.name}/${filename}`);
-                                return;
+                // Delegate to reusable setupSymlinkWatcher (also called after error recovery)
+                setupSymlinkWatcher(photon.name, photon.path);
+            }
+            else {
+                // Non-symlinked photon (e.g. ~/.photon/boards.photon.ts) — watch both
+                // the source file and its asset folder if they're outside the workingDir
+                // (workingDir is already covered by the recursive watcher above)
+                const photonDir = path.dirname(photon.path);
+                if (!photonDir.startsWith(workingDir)) {
+                    try {
+                        const srcFileName = path.basename(photon.path);
+                        const srcDirWatcher = watch(photonDir, (eventType, filename) => {
+                            if (filename === srcFileName) {
+                                void handleFileChange(photon.name);
                             }
-                            logger.info(`📁 Asset change detected: ${photon.name}/${filename}`);
-                            handleFileChange(photon.name);
+                        });
+                        srcDirWatcher.on('error', () => { });
+                        watchers.push(srcDirWatcher);
+                        const assetFolder = path.join(photonDir, photon.name);
+                        if (existsSync(assetFolder)) {
+                            const assetWatcher = watch(assetFolder, { recursive: true }, (eventType, filename) => {
+                                if (filename) {
+                                    if (filename.endsWith('.json') ||
+                                        filename.startsWith('boards/') ||
+                                        filename === 'data.json') {
+                                        return;
+                                    }
+                                    logger.info(`📁 Asset change detected: ${photon.name}/${filename}`);
+                                    void handleFileChange(photon.name);
+                                }
+                            });
+                            assetWatcher.on('error', () => { });
+                            watchers.push(assetWatcher);
                         }
-                    });
-                    assetWatcher.on('error', (err) => {
-                        logger.warn(`Watcher error for ${photon.name}/: ${err.message}`);
-                    });
-                    watchers.push(assetWatcher);
-                    logger.info(`👀 Watching ${photon.name}/ (symlinked → ${assetFolder})`);
-                }
-                else {
-                    logger.debug(`⏭️ Skipping ${photon.name}: asset folder not found at ${assetFolder}`);
+                        logger.info(`👀 Watching ${photon.name} (${photonDir})`);
+                    }
+                    catch {
+                        logger.debug(`⏭️ Could not watch ${photon.name}: ${photon.path}`);
+                    }
                 }
             }
-            else {
-                logger.debug(`⏭️ Skipping ${photon.name}: not a symlink`);
-            }
         }
         catch (err) {
-            logger.debug(`⏭️ Skipping ${photon.name}: ${err instanceof Error ? err.message : err}`);
+            logger.debug(`⏭️ Skipping ${photon.name}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     // Watch bundled photon asset folders
@@ -2824,14 +1242,20 @@ export async function startBeam(rawWorkingDir, port) {
         try {
             const photonWatcher = watch(photonPath, (eventType) => {
                 if (eventType === 'change') {
-                    handleFileChange(photonName);
+                    void handleFileChange(photonName);
                 }
             });
-            photonWatcher.on('error', () => { });
+            photonWatcher.on('error', (e) => {
+                logger.debug('File watcher error', { photon: photonName, error: getErrorMessage(e) });
+            });
             watchers.push(photonWatcher);
         }
-        catch {
-            // Ignore errors
+        catch (e) {
+            // watch() throws if the path doesn't exist yet — photon may still be installing
+            logger.debug('Could not watch photon file', {
+                photon: photonName,
+                error: getErrorMessage(e),
+            });
         }
         const assetFolder = path.join(photonDir, photonName);
         try {
@@ -2844,7 +1268,7 @@ export async function startBeam(rawWorkingDir, port) {
                         return;
                     }
                     logger.info(`📁 Asset change detected: ${photonName}/${filename}`);
-                    handleFileChange(photonName);
+                    void handleFileChange(photonName);
                 }
             });
             assetWatcher.on('error', () => { });
@@ -2860,8 +1284,9 @@ export async function startBeam(rawWorkingDir, port) {
     // Watch the parent directory (atomic writes via rename can miss single-file watches)
     // ══════════════════════════════════════════════════════════════════════════════
     try {
-        const configDir = path.dirname(CONFIG_FILE);
-        // Ensure directory exists before watching (fresh install may not have ~/.photon yet)
+        const configFile = getConfigFilePath(workingDir);
+        const configDir = path.dirname(configFile);
+        // Ensure directory exists before watching (fresh install may not have config.json yet)
         if (!existsSync(configDir)) {
             mkdirSync(configDir, { recursive: true });
         }
@@ -2871,405 +1296,116 @@ export async function startBeam(rawWorkingDir, port) {
                 return;
             if (configDebounce)
                 clearTimeout(configDebounce);
-            configDebounce = setTimeout(async () => {
-                configDebounce = null;
-                let newConfig;
-                try {
-                    const data = await fs.readFile(CONFIG_FILE, 'utf-8');
-                    newConfig = migrateConfig(JSON.parse(data));
-                }
-                catch (err) {
-                    logger.warn(`⚠️ Failed to parse config.json: ${err instanceof Error ? err.message : err}`);
-                    return;
-                }
-                const oldServers = savedConfig.mcpServers || {};
-                const newServers = newConfig.mcpServers || {};
-                const oldKeys = new Set(Object.keys(oldServers));
-                const newKeys = new Set(Object.keys(newServers));
-                const added = [...newKeys].filter((k) => !oldKeys.has(k));
-                const removed = [...oldKeys].filter((k) => !newKeys.has(k));
-                const kept = [...newKeys].filter((k) => oldKeys.has(k));
-                const modified = kept.filter((k) => JSON.stringify(oldServers[k]) !== JSON.stringify(newServers[k]));
-                if (added.length === 0 && removed.length === 0 && modified.length === 0) {
-                    // Also sync photon config changes (env vars etc.)
-                    savedConfig.photons = newConfig.photons || {};
-                    return;
-                }
-                logger.info(`🔧 config.json changed — added: [${added}], removed: [${removed}], modified: [${modified}]`);
-                // Remove MCPs
-                for (const name of removed) {
-                    const idx = externalMCPs.findIndex((m) => m.name === name);
-                    if (idx !== -1)
-                        externalMCPs.splice(idx, 1);
-                    // Clean up clients
+            configDebounce = setTimeout(() => {
+                void (async () => {
+                    configDebounce = null;
+                    let newConfig;
                     try {
+                        const data = await fs.readFile(configFile, 'utf-8');
+                        newConfig = migrateConfig(JSON.parse(data));
+                    }
+                    catch (err) {
+                        logger.warn(`⚠️ Failed to parse config.json: ${err instanceof Error ? err.message : String(err)}`);
+                        return;
+                    }
+                    const oldServers = savedConfig.mcpServers || {};
+                    const newServers = newConfig.mcpServers || {};
+                    const oldKeys = new Set(Object.keys(oldServers));
+                    const newKeys = new Set(Object.keys(newServers));
+                    const added = [...newKeys].filter((k) => !oldKeys.has(k));
+                    const removed = [...oldKeys].filter((k) => !newKeys.has(k));
+                    const kept = [...newKeys].filter((k) => oldKeys.has(k));
+                    const modified = kept.filter((k) => JSON.stringify(oldServers[k]) !== JSON.stringify(newServers[k]));
+                    if (added.length === 0 && removed.length === 0 && modified.length === 0) {
+                        // Also sync photon config changes (env vars etc.)
+                        savedConfig.photons = newConfig.photons || {};
+                        return;
+                    }
+                    logger.info(`🔧 config.json changed — added: [${added.join(', ')}], removed: [${removed.join(', ')}], modified: [${modified.join(', ')}]`);
+                    // Remove MCPs — do all synchronous Map mutations first, then close async
+                    const removedSdkClients = [];
+                    for (const name of removed) {
+                        const idx = externalMCPs.findIndex((m) => m.name === name);
+                        if (idx !== -1)
+                            externalMCPs.splice(idx, 1);
                         const sdkClient = externalMCPSDKClients.get(name);
-                        if (sdkClient) {
-                            await sdkClient.close();
-                            externalMCPSDKClients.delete(name);
+                        if (sdkClient)
+                            removedSdkClients.push({ name, client: sdkClient });
+                        externalMCPSDKClients.delete(name);
+                        externalMCPClients.delete(name);
+                        logger.info(`🔌 Removed external MCP: ${name}`);
+                    }
+                    // Close SDK clients after all Maps are consistent
+                    for (const { name, client } of removedSdkClients) {
+                        try {
+                            await client.close();
+                        }
+                        catch {
+                            /* ignore */
                         }
                     }
-                    catch {
-                        /* ignore */
+                    // Add new MCPs
+                    if (added.length > 0) {
+                        const addConfig = {
+                            photons: {},
+                            mcpServers: Object.fromEntries(added.map((k) => [k, newServers[k]])),
+                        };
+                        const newMCPs = await loadExternalMCPs(addConfig);
+                        externalMCPs.push(...newMCPs);
+                        for (const m of newMCPs) {
+                            logger.info(`🔌 Added external MCP: ${m.name} (${m.connected ? m.methods.length + ' tools' : 'failed'})`);
+                        }
                     }
-                    externalMCPClients.delete(name);
-                    logger.info(`🔌 Removed external MCP: ${name}`);
-                }
-                // Add new MCPs
-                if (added.length > 0) {
-                    const addConfig = {
-                        photons: {},
-                        mcpServers: Object.fromEntries(added.map((k) => [k, newServers[k]])),
-                    };
-                    const newMCPs = await loadExternalMCPs(addConfig);
-                    externalMCPs.push(...newMCPs);
-                    for (const m of newMCPs) {
-                        logger.info(`🔌 Added external MCP: ${m.name} (${m.connected ? m.methods.length + ' tools' : 'failed'})`);
+                    // Reconnect modified MCPs — synchronous cleanup first, then async reconnect
+                    const modifiedSdkClients = [];
+                    for (const name of modified) {
+                        const idx = externalMCPs.findIndex((m) => m.name === name);
+                        if (idx !== -1)
+                            externalMCPs.splice(idx, 1);
+                        const sdkClient = externalMCPSDKClients.get(name);
+                        if (sdkClient)
+                            modifiedSdkClients.push({ name, client: sdkClient });
+                        externalMCPSDKClients.delete(name);
+                        externalMCPClients.delete(name);
                     }
-                }
-                // Reconnect modified MCPs
-                for (const name of modified) {
-                    const idx = externalMCPs.findIndex((m) => m.name === name);
-                    if (idx !== -1) {
-                        // Clean up old clients
+                    // Close old SDK clients
+                    for (const { client } of modifiedSdkClients) {
                         try {
-                            const sdkClient = externalMCPSDKClients.get(name);
-                            if (sdkClient) {
-                                await sdkClient.close();
-                                externalMCPSDKClients.delete(name);
-                            }
+                            await client.close();
                         }
                         catch {
                             /* ignore */
                         }
-                        externalMCPClients.delete(name);
-                        externalMCPs.splice(idx, 1);
                     }
-                    // Reconnect with new config
-                    const modConfig = {
-                        photons: {},
-                        mcpServers: { [name]: newServers[name] },
-                    };
-                    const reconnected = await loadExternalMCPs(modConfig);
-                    externalMCPs.push(...reconnected);
-                    logger.info(`🔌 Reconnected external MCP: ${name}`);
-                }
-                // Update savedConfig
-                savedConfig.mcpServers = newConfig.mcpServers || {};
-                savedConfig.photons = newConfig.photons || {};
-                broadcastPhotonChange();
+                    // Reconnect all modified MCPs
+                    for (const name of modified) {
+                        const modConfig = {
+                            photons: {},
+                            mcpServers: { [name]: newServers[name] },
+                        };
+                        const reconnected = await loadExternalMCPs(modConfig);
+                        externalMCPs.push(...reconnected);
+                        logger.info(`🔌 Reconnected external MCP: ${name}`);
+                    }
+                    // Update savedConfig
+                    savedConfig.mcpServers = newConfig.mcpServers || {};
+                    savedConfig.photons = newConfig.photons || {};
+                    broadcastPhotonChange();
+                })();
             }, 500);
         });
         configWatcher.on('error', (err) => {
             logger.warn(`Config watcher error: ${err.message}`);
         });
         watchers.push(configWatcher);
-        logger.info(`👀 Watching config.json for external MCP changes`);
-    }
-    catch (error) {
-        logger.warn(`Config watching not available: ${error}`);
-    }
-}
-/**
- * Configure a photon via MCP
- */
-async function configurePhotonViaMCP(photonName, config, photons, photonMCPs, loader, savedConfig) {
-    // Find the photon (configured or unconfigured)
-    const photonIndex = photons.findIndex((p) => p.name === photonName);
-    if (photonIndex === -1) {
-        return { success: false, error: `Photon not found: ${photonName}` };
-    }
-    // Apply config to environment
-    for (const [key, value] of Object.entries(config)) {
-        process.env[key] = String(value);
-    }
-    // Save config to file (merge with existing config for edit mode)
-    savedConfig.photons[photonName] = { ...(savedConfig.photons[photonName] || {}), ...config };
-    await saveConfig(savedConfig);
-    const targetPhoton = photons[photonIndex];
-    const isReconfigure = targetPhoton.configured === true;
-    // Try to reload the photon
-    try {
-        const mcp = isReconfigure
-            ? await loader.reloadFile(targetPhoton.path)
-            : await loader.loadFile(targetPhoton.path);
-        const instance = mcp.instance;
-        if (!instance) {
-            throw new Error('Failed to create instance');
-        }
-        photonMCPs.set(photonName, mcp);
-        backfillEnvDefaults(instance, targetPhoton.requiredParams || []);
-        // Extract schema for UI
-        const extractor = new SchemaExtractor();
-        const configSource = await fs.readFile(targetPhoton.path, 'utf-8');
-        const { tools: schemas, templates } = extractor.extractAllFromSource(configSource);
-        mcp.schemas = schemas;
-        // Get UI assets for linking
-        const uiAssets = mcp.assets?.ui || [];
-        const lifecycleMethods = ['onInitialize', 'onShutdown', 'constructor'];
-        const methods = schemas
-            .filter((schema) => !lifecycleMethods.includes(schema.name))
-            .map((schema) => {
-            const linkedAsset = uiAssets.find((ui) => ui.linkedTool === schema.name);
-            return {
-                name: schema.name,
-                description: schema.description || '',
-                params: schema.inputSchema || { type: 'object', properties: {}, required: [] },
-                returns: { type: 'object' },
-                autorun: schema.autorun || false,
-                outputFormat: schema.outputFormat,
-                layoutHints: schema.layoutHints,
-                buttonLabel: schema.buttonLabel,
-                icon: schema.icon,
-                linkedUi: linkedAsset?.id,
-            };
-        });
-        // Add templates as methods
-        templates.forEach((template) => {
-            if (!lifecycleMethods.includes(template.name)) {
-                methods.push({
-                    name: template.name,
-                    description: template.description || '',
-                    params: template.inputSchema || { type: 'object', properties: {}, required: [] },
-                    returns: { type: 'object' },
-                    isTemplate: true,
-                    outputFormat: 'markdown',
-                });
-            }
-        });
-        // Apply @visibility annotations
-        applyMethodVisibility(configSource, methods);
-        // Check if this is an App
-        const mainMethod = methods.find((m) => m.name === 'main' && m.linkedUi);
-        const isApp = !!mainMethod;
-        // Replace unconfigured photon with configured one
-        const configuredPhoton = {
-            id: generatePhotonId(targetPhoton.path),
-            name: photonName,
-            path: targetPhoton.path,
-            configured: true,
-            methods,
-            isApp,
-            appEntry: mainMethod,
-            assets: mcp.assets,
-            ...(mcp.injectedPhotons &&
-                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
-        };
-        photons[photonIndex] = configuredPhoton;
-        logger.info(`✅ ${photonName} configured via MCP`);
-        // Notify connected MCP clients about tools list change
-        broadcastNotification('notifications/tools/list_changed', {});
-        broadcastToBeam('beam/configured', { photon: configuredPhoton });
-        return { success: true };
-    }
-    catch (error) {
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        logger.error(`Failed to configure ${photonName} via MCP: ${errorMsg}`);
-        return { success: false, error: errorMsg };
-    }
-}
-/**
- * Reload a photon via MCP
- */
-async function reloadPhotonViaMCP(photonName, photons, photonMCPs, loader, savedConfig, broadcastChange) {
-    // Find the photon
-    const photonIndex = photons.findIndex((p) => p.name === photonName);
-    if (photonIndex === -1) {
-        return { success: false, error: `Photon not found: ${photonName}` };
-    }
-    const photon = photons[photonIndex];
-    const photonPath = photon.path;
-    // Get saved config for this photon
-    const config = savedConfig.photons[photonName] || {};
-    // Apply config to environment
-    for (const [key, value] of Object.entries(config)) {
-        process.env[key] = value;
-    }
-    try {
-        // Reload the photon (clears compiled cache for hot reload)
-        const mcp = await loader.reloadFile(photonPath);
-        const instance = mcp.instance;
-        if (!instance) {
-            throw new Error('Failed to create instance');
+        // Only log if config.json actually exists
+        if (existsSync(configFile)) {
+            logger.info(`👀 Watching config.json for external MCP changes`);
         }
-        photonMCPs.set(photonName, mcp);
-        backfillEnvDefaults(instance, photon.requiredParams || []);
-        // Extract schema for UI
-        const extractor = new SchemaExtractor();
-        const reloadSrc = await fs.readFile(photonPath, 'utf-8');
-        const { tools: schemas, templates } = extractor.extractAllFromSource(reloadSrc);
-        mcp.schemas = schemas;
-        const lifecycleMethods = ['onInitialize', 'onShutdown', 'constructor'];
-        const uiAssets = mcp.assets?.ui || [];
-        const methods = schemas
-            .filter((schema) => !lifecycleMethods.includes(schema.name))
-            .map((schema) => {
-            const linkedAsset = uiAssets.find((ui) => ui.linkedTool === schema.name);
-            return {
-                name: schema.name,
-                description: schema.description || '',
-                params: schema.inputSchema || { type: 'object', properties: {}, required: [] },
-                returns: { type: 'object' },
-                autorun: schema.autorun || false,
-                outputFormat: schema.outputFormat,
-                layoutHints: schema.layoutHints,
-                buttonLabel: schema.buttonLabel,
-                icon: schema.icon,
-                linkedUi: linkedAsset?.id,
-            };
-        });
-        // Add templates as methods
-        templates.forEach((template) => {
-            if (!lifecycleMethods.includes(template.name)) {
-                methods.push({
-                    name: template.name,
-                    description: template.description || '',
-                    params: template.inputSchema || { type: 'object', properties: {}, required: [] },
-                    returns: { type: 'object' },
-                    isTemplate: true,
-                    outputFormat: 'markdown',
-                });
-            }
-        });
-        // Apply @visibility annotations
-        applyMethodVisibility(reloadSrc, methods);
-        // Check if this is an App
-        const mainMethod = methods.find((m) => m.name === 'main' && m.linkedUi);
-        // Extract class metadata from source
-        const reloadClassMeta = extractClassMetadataFromSource(reloadSrc);
-        // Update photon info
-        const reloadedPhoton = {
-            id: generatePhotonId(photonPath),
-            name: photonName,
-            path: photonPath,
-            configured: true,
-            methods,
-            isApp: !!mainMethod,
-            appEntry: mainMethod,
-            description: reloadClassMeta.description,
-            icon: reloadClassMeta.icon,
-            internal: reloadClassMeta.internal,
-            ...(mcp.injectedPhotons &&
-                mcp.injectedPhotons.length > 0 && { injectedPhotons: mcp.injectedPhotons }),
-        };
-        photons[photonIndex] = reloadedPhoton;
-        logger.info(`🔄 ${photonName} reloaded via MCP`);
-        // Notify clients about the change
-        broadcastChange();
-        return { success: true, photon: reloadedPhoton };
     }
     catch (error) {
-        const errorMsg = error instanceof Error ? error.message : String(error);
-        logger.error(`Failed to reload ${photonName} via MCP: ${errorMsg}`);
-        return { success: false, error: errorMsg };
-    }
-}
-/**
- * Remove a photon via MCP
- */
-async function removePhotonViaMCP(photonName, photons, photonMCPs, savedConfig, broadcastChange) {
-    // Find and remove the photon
-    const photonIndex = photons.findIndex((p) => p.name === photonName);
-    if (photonIndex === -1) {
-        return { success: false, error: `Photon not found: ${photonName}` };
-    }
-    // Remove from arrays and maps
-    photons.splice(photonIndex, 1);
-    photonMCPs.delete(photonName);
-    // Remove saved config
-    if (savedConfig.photons[photonName]) {
-        delete savedConfig.photons[photonName];
-        await saveConfig(savedConfig);
-    }
-    logger.info(`🗑️ ${photonName} removed via MCP`);
-    // Notify clients about the change
-    broadcastChange();
-    return { success: true };
-}
-/**
- * Update photon or method metadata via MCP
- */
-async function updateMetadataViaMCP(photonName, methodName, metadata, photons) {
-    // Find the photon
-    const photonIndex = photons.findIndex((p) => p.name === photonName);
-    if (photonIndex === -1) {
-        return { success: false, error: `Photon not found: ${photonName}` };
-    }
-    const photon = photons[photonIndex];
-    if (methodName) {
-        // Update method metadata
-        if (!photon.configured || !photon.methods) {
-            return { success: false, error: 'Photon is not configured or has no methods' };
-        }
-        const method = photon.methods.find((m) => m.name === methodName);
-        if (!method) {
-            return { success: false, error: `Method not found: ${methodName}` };
-        }
-        // Update method metadata
-        if (metadata.description !== undefined) {
-            method.description = metadata.description;
-        }
-        if (metadata.icon !== undefined) {
-            method.icon = metadata.icon;
-        }
-        logger.info(`📝 Updated metadata for ${photonName}/${methodName}`);
-    }
-    else {
-        // Update photon metadata
-        if (metadata.description !== undefined) {
-            photon.description = metadata.description;
-        }
-        if (metadata.icon !== undefined) {
-            photon.icon = metadata.icon;
-        }
-        logger.info(`📝 Updated metadata for ${photonName}`);
-    }
-    return { success: true };
-}
-/**
- * Generate rich help markdown for a photon using PhotonDocExtractor + TemplateManager.
- * Checks for an existing .md file first; generates and saves one if missing.
- */
-async function generatePhotonHelpMarkdown(photonName, photons) {
-    const photon = photons.find((p) => p.name === photonName);
-    if (!photon) {
-        throw new Error(`Photon not found: ${photonName}`);
-    }
-    if (!photon.path) {
-        throw new Error(`Photon path not available: ${photonName}`);
-    }
-    const sourceDir = path.dirname(photon.path);
-    const mdPath = path.join(sourceDir, `${photonName}.md`);
-    // Check if .md file already exists and is newer than the photon source
-    try {
-        const [mdStat, srcStat] = await Promise.all([fs.stat(mdPath), fs.stat(photon.path)]);
-        if (mdStat.mtimeMs >= srcStat.mtimeMs) {
-            const existing = await fs.readFile(mdPath, 'utf-8');
-            if (existing.trim()) {
-                return existing;
-            }
-        }
-    }
-    catch {
-        // .md doesn't exist or stat failed - regenerate
-    }
-    // Extract metadata and render template
-    const extractor = new PhotonDocExtractor(photon.path);
-    const metadata = await extractor.extractFullMetadata();
-    // Use TemplateManager to render the photon.md template
-    const templateMgr = new TemplateManager(sourceDir);
-    await templateMgr.ensureTemplates();
-    const markdown = await templateMgr.renderTemplate('photon.md', metadata);
-    // Try to save the generated .md file for future use
-    try {
-        await fs.writeFile(mdPath, markdown, 'utf-8');
-        logger.info(`📄 Generated help doc: ${mdPath}`);
-    }
-    catch {
-        // Write may fail for bundled/read-only photons - that's fine
-        logger.debug(`Could not save help doc to ${mdPath} (read-only?)`);
+        logger.warn(`Config watching not available: ${String(error)}`);
     }
-    return markdown;
 }
 /**
  * Gracefully stop Beam server and clean up resources.
@@ -3285,10 +1421,7 @@ export async function stopBeam() {
     }
     // Wait for all clients to close (with timeout)
     if (closePromises.length > 0) {
-        await Promise.race([
-            Promise.all(closePromises),
-            new Promise((resolve) => setTimeout(resolve, 1000)), // 1 second timeout
-        ]);
+        await withTimeout(Promise.all(closePromises), 1000, 'MCP client close timeout').catch(() => { }); // Timeout during shutdown is expected
     }
     externalMCPSDKClients.clear();
     externalMCPClients.clear();