fraim 2.0.159 → 2.0.161

package/dist/src/ai-hub/server.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiHubServer = void 0;
 exports.findAvailablePort = findAvailablePort;
+exports.findAvailablePortExcluding = findAvailablePortExcluding;
 const express_1 = __importDefault(require("express"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
@@ -12,6 +13,7 @@ const net_1 = __importDefault(require("net"));
 const os_1 = __importDefault(require("os"));
 const crypto_1 = require("crypto");
 const child_process_1 = require("child_process");
+const https_1 = __importDefault(require("https"));
 const types_1 = require("../first-run/types");
 const PERSONA_AVATAR_SEEDS = {
     maestro: { seed: 'MAESTRO-founder-mode', bg: 'fde68a' },
@@ -40,6 +42,7 @@ function buildPersonaAvatarUrl(personaKey) {
 const catalog_1 = require("./catalog");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const hosts_1 = require("./hosts");
+const manager_turns_1 = require("./manager-turns");
 const preferences_1 = require("./preferences");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 function loadPersonaCapabilityModule() {
@@ -282,12 +285,12 @@ function deriveStages(run, projectPath) {
     const completedWithoutPhaseTelemetry = run.status === 'completed' &&
         currentIndex < 0 &&
         historyMap.size === 0;
+    if (completedWithoutPhaseTelemetry) {
+        return [];
+    }
     return declaredPath.map((phase, index) => {
         let state;
-        if (completedWithoutPhaseTelemetry) {
-            state = 'done';
-        }
-        else if (currentIndex < 0) {
+        if (currentIndex < 0) {
             state = 'upcoming';
         }
         else if (index < currentIndex) {
@@ -411,6 +414,10 @@ class AiHubServer {
         this.runRegistry = new AiHubRunRegistry();
         this.projectPath = options.projectPath || process.cwd();
         this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
+        this.wordTaskpaneDir = options.wordTaskpaneDir ?? resolveWordTaskpaneDir(this.projectPath);
+        this.folderPicker = options.folderPicker ?? pickProjectPath;
+        this.httpsPort = options.httpsPort;
+        this.certBundle = options.certBundle;
         this.hostRuntime = options.hostRuntime || (process.env.FRAIM_AI_HUB_FAKE_HOST === '1' ? new hosts_1.FakeHostRuntime() : new hosts_1.CliHostRuntime());
         if (options.dbService !== undefined) {
             this.dbService = options.dbService;
@@ -421,11 +428,13 @@ class AiHubServer {
             this.ownsDbService = this.dbService !== undefined;
         }
         this.app.use(express_1.default.json());
-        // CORS for browser extension and Office add-in task panes calling localhost Hub
+        // CORS + Chrome Private Network Access for browser extensions and Office add-in task panes
+        // calling the Hub from a public origin (word-edit.officeapps.live.com, etc.).
         this.app.use((_req, res, next) => {
             res.setHeader('Access-Control-Allow-Origin', '*');
             res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
             res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+            res.setHeader('Access-Control-Allow-Private-Network', 'true');
             if (_req.method === 'OPTIONS') {
                 res.sendStatus(204);
                 return;
@@ -433,6 +442,60 @@ class AiHubServer {
             next();
         });
         this.app.use('/ai-hub', express_1.default.static(resolveAiHubPublicDir()));
+        // Issue #489: Serve the Word task pane assets at /word-taskpane/*.
+        // Office JS appends ?_host_Info=Word$Win32$... to every request — we must
+        // strip the query string before resolving the file path, otherwise every
+        // request returns 404.  express.static does NOT strip query strings, so we
+        // use a custom middleware that resolves the pathname manually.
+        if (this.wordTaskpaneDir) {
+            const wordDir = this.wordTaskpaneDir; // capture for closure
+            this.app.use('/word-taskpane', (req, res, next) => {
+                // Chrome Private Network Access: public origin (word-edit.officeapps.live.com)
+                // loading a private-network resource (localhost) requires this header on both the
+                // preflight OPTIONS response and the final GET response.
+                res.setHeader('Access-Control-Allow-Private-Network', 'true');
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+                if (req.method === 'OPTIONS') {
+                    res.sendStatus(204);
+                    return;
+                }
+                // Strip query string — Office appends ?_host_Info=Word$Win32$... to every request
+                const { pathname } = new URL(req.url, 'http://localhost');
+                const target = pathname === '/' || pathname === '' ? '/taskpane.html' : pathname;
+                // Prevent path traversal
+                const safeTarget = path_1.default.normalize(target).replace(/^(\.\.(\/|\\|$))+/, '');
+                const filePath = path_1.default.join(wordDir, safeTarget);
+                if (!filePath.startsWith(wordDir + path_1.default.sep) && filePath !== wordDir) {
+                    res.status(403).end();
+                    return;
+                }
+                const ext = path_1.default.extname(filePath);
+                const contentTypes = {
+                    '.html': 'text/html; charset=utf-8',
+                    '.css': 'text/css; charset=utf-8',
+                    '.js': 'application/javascript; charset=utf-8',
+                    '.xml': 'application/xml; charset=utf-8',
+                };
+                const contentType = contentTypes[ext] || 'text/plain; charset=utf-8';
+                fs_1.default.readFile(filePath, (err, data) => {
+                    if (err) {
+                        next(); // fall through to 404
+                        return;
+                    }
+                    res.setHeader('Content-Type', contentType);
+                    res.end(data);
+                });
+            });
+        }
+        this.app.get(['/word-taskpane/config.js', '/powerpoint-taskpane/config.js'], (_req, res) => {
+            const port = this.httpPort || 43091;
+            const origin = `http://127.0.0.1:${port}`;
+            res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.end(`window.FRAIM_HUB_ORIGIN=${JSON.stringify(origin)};\n`);
+        });
         this.app.get('/health', (_req, res) => {
             res.json({ status: 'ok', service: 'fraim-ai-hub' });
         });
@@ -440,78 +503,13 @@ class AiHubServer {
         this.app.get('/api/health', (_req, res) => {
             res.json({ status: 'ok', service: 'fraim-ai-hub' });
         });
-        // Trigger endpoint for external surfaces (browser extension, Office add-ins, tray).
-        // Starts a real Hub run and returns the runId for polling via GET /api/ai-hub/runs/:runId.
-        this.app.post('/api/trigger', (req, res) => {
-            const { employeeId, jobName, context, projectPath } = req.body;
-            if (!employeeId || !jobName) {
-                res.status(400).json({ error: 'employeeId and jobName are required' });
-                return;
-            }
-            const contextSummary = [
-                context?.sourceApp ? `Source: ${context.sourceApp}` : '',
-                context?.fileName ? `File: ${context.fileName}` : '',
-                context?.text ? `Context:\n${context.text.slice(0, 500)}` : '',
-            ].filter(Boolean).join('\n');
-            const message = `/fraim ${jobName}\n\n${contextSummary}`.trim();
-            const hostId = 'claude';
-            const resolvedPath = projectPath || this.projectPath;
-            try {
-                const employee = this.hostRuntime.detectEmployees().find((e) => e.id === hostId);
-                if (!employee?.available) {
-                    res.status(503).json({ error: `${hostId} is not available on this machine` });
-                    return;
-                }
-                const now = new Date().toISOString();
-                const run = {
-                    id: (0, crypto_1.randomUUID)(),
-                    jobId: jobName,
-                    hostId,
-                    projectPath: resolvedPath,
-                    status: 'running',
-                    createdAt: now,
-                    updatedAt: now,
-                    messages: [(0, hosts_1.createHubMessage)('manager', message)],
-                    events: [(0, hosts_1.createHubEvent)('system', `Starting ${hostId} via ${context?.sourceApp || 'external-surface'} in ${resolvedPath}`)],
-                    currentPhase: null,
-                    phaseHistory: [],
-                    totals: emptyTotals(),
-                    lastStatusChangeAt: now,
-                    personaKey: getProtectedPersonaForHubJob(jobName),
-                };
-                const child = this.hostRuntime.startRun(hostId, resolvedPath, message, {
-                    onEvent: (event, channel) => {
-                        this.runRegistry.update(run.id, (current) => {
-                            if (event.sessionId)
-                                current.sessionId = event.sessionId;
-                            if (event.message)
-                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
-                            if (event.raw)
-                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
-                        });
-                    },
-                    onExit: (exitCode) => {
-                        this.runRegistry.update(run.id, (current) => {
-                            current.exitCode = exitCode;
-                            current.status = exitCode === 0 ? 'completed' : 'failed';
-                            current.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
-                        });
-                        this.runRegistry.dispose(run.id);
-                    },
-                });
-                this.runRegistry.create(run, child);
-                res.json({ runId: run.id, status: 'started', employee: employeeId, job: jobName });
-            }
-            catch (err) {
-                res.status(500).json({ error: err.message });
-            }
-        });
         this.registerRoutes();
     }
     getApp() {
         return this.app;
     }
     async start(port) {
+        this.httpPort = port;
         if (this.dbService) {
             try {
                 await this.dbService.connect();
@@ -526,18 +524,31 @@ class AiHubServer {
             this.httpServer.once('listening', () => resolve());
             this.httpServer.once('error', (error) => reject(error));
         });
+        // Start HTTPS server when a cert bundle and port are provided.
+        // Word Online requires HTTPS; the HTTPS server shares the same Express app
+        // so all routes (including /word-taskpane/*) are available over both protocols.
+        if (this.httpsPort && this.certBundle) {
+            await new Promise((resolve, reject) => {
+                this.httpsServer = https_1.default.createServer({ key: this.certBundle.key, cert: this.certBundle.cert }, this.app);
+                this.httpsServer.listen(this.httpsPort, '127.0.0.1');
+                this.httpsServer.once('listening', () => resolve());
+                this.httpsServer.once('error', (error) => reject(error));
+            });
+        }
     }
     async stop() {
+        const closeServer = (srv) => new Promise((resolve, reject) => {
+            srv.close((error) => { if (error)
+                reject(error);
+            else
+                resolve(); });
+        });
+        if (this.httpsServer) {
+            await closeServer(this.httpsServer);
+            this.httpsServer = undefined;
+        }
         if (this.httpServer) {
-            await new Promise((resolve, reject) => {
-                this.httpServer.close((error) => {
-                    if (error) {
-                        reject(error);
-                        return;
-                    }
-                    resolve();
-                });
-            });
+            await closeServer(this.httpServer);
             this.httpServer = undefined;
         }
         if (this.ownsDbService && this.dbService) {
@@ -545,6 +556,7 @@ class AiHubServer {
             this.dbService = undefined;
         }
     }
+    getHttpsPort() { return this.httpsPort; }
     async bootstrapResponse(projectPath, apiKey) {
         const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
         const employees = this.hostRuntime.detectEmployees();
@@ -585,6 +597,45 @@ class AiHubServer {
             activeRun,
         };
     }
+    resolveHubJob(projectPath, jobId) {
+        const employeeJob = (0, catalog_1.discoverEmployeeJobs)(projectPath).find((job) => job.id === jobId);
+        if (employeeJob)
+            return { id: employeeJob.id, stubPath: employeeJob.stubPath };
+        const managerTemplate = (0, catalog_1.discoverManagerTemplates)(projectPath).find((job) => job.id === jobId);
+        if (managerTemplate)
+            return { id: managerTemplate.id, stubPath: managerTemplate.stubPath };
+        return null;
+    }
+    prepareStartPayload(projectPath, hostId, selectedJobId, instructions) {
+        const explicit = (0, manager_turns_1.extractExplicitFraimInvocation)(instructions);
+        const resolvedJobId = explicit?.jobId || selectedJobId;
+        if (!resolvedJobId) {
+            throw new Error('Choose a FRAIM job before starting a run, or start with /fraim <job-id>.');
+        }
+        if (resolvedJobId === '__freeform__') {
+            return {
+                jobId: resolvedJobId,
+                message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions),
+            };
+        }
+        const resolvedJob = this.resolveHubJob(projectPath, resolvedJobId);
+        const absoluteStubPath = resolvedJob?.stubPath
+            ? [projectPath, resolvedJob.stubPath].join('/').replace(/\\/g, '/').replace(/\/+/g, '/')
+            : undefined;
+        return {
+            jobId: resolvedJobId,
+            message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions, absoluteStubPath),
+        };
+    }
+    prepareContinueMessage(run, instructions, coachingJobId) {
+        // coachingJobId is set when the user selected a manager coaching template
+        // (e.g. follow-your-mentor). When present, it overrides the run's own jobId
+        // as the target of the FRAIM invocation. The server picks the correct
+        // invocation prefix ($fraim / /fraim) based on run.hostId — the UI never
+        // passes raw invocation syntax.
+        const effectiveJobId = coachingJobId || run.jobId;
+        return (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions);
+    }
     async computePersonas(apiKey) {
         const allBundles = listHubPersonaBundles();
         const fallbackPersonas = allBundles.map((bundle) => ({
@@ -622,13 +673,60 @@ class AiHubServer {
         }
     }
     registerRoutes() {
+        // Issue #478: Serve the PowerPoint task pane HTML and manifest.
+        // Office JS appends query strings (?_host_Info=PowerPoint$Win32$...) to every
+        // request, so we must strip them before resolving the file path. Use a custom
+        // route rather than express.static so we can apply the new URL().pathname fix.
+        this.app.get(/^\/powerpoint-taskpane(\/.*)?$/, (req, res) => {
+            const taskpaneDir = resolveTaskpaneDir('powerpoint-taskpane');
+            // Strip query string — Office appends ?_host_Info=PowerPoint$... to every fetch.
+            const { pathname } = new URL(req.url, 'http://localhost');
+            // Map root /powerpoint-taskpane/ to index.html
+            const relativePath = pathname.replace(/^\/powerpoint-taskpane\/?/, '') || 'index.html';
+            const filePath = path_1.default.join(taskpaneDir, relativePath);
+            if (!filePath.startsWith(taskpaneDir)) {
+                // Path traversal guard
+                res.status(403).end();
+                return;
+            }
+            const ext = path_1.default.extname(filePath).toLowerCase();
+            const contentTypeMap = {
+                '.html': 'text/html; charset=utf-8',
+                '.xml': 'application/xml',
+                '.js': 'application/javascript',
+                '.css': 'text/css',
+                '.png': 'image/png',
+            };
+            const contentType = contentTypeMap[ext] || 'text/plain';
+            fs_1.default.readFile(filePath, (err, data) => {
+                if (err) {
+                    res.status(404).end('Not found');
+                    return;
+                }
+                res.setHeader('Content-Type', contentType);
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.end(data);
+            });
+        });
         this.app.get('/api/ai-hub/bootstrap', async (req, res) => {
-            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+            let projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
                 ? req.query.projectPath
-                : this.projectPath;
+                : null;
+            // If no explicit projectPath but a file:// docUrl was passed (Word Desktop),
+            // derive the project directory from the document's local path.
+            if (!projectPath && typeof req.query.docUrl === 'string' && req.query.docUrl.startsWith('file://')) {
+                try {
+                    const fileUrl = new URL(req.query.docUrl);
+                    const rawPath = process.platform === 'win32'
+                        ? fileUrl.pathname.replace(/^\/([A-Za-z]:)/, '$1')
+                        : fileUrl.pathname;
+                    projectPath = path_1.default.dirname(decodeURIComponent(rawPath));
+                }
+                catch { }
+            }
             // Read API key from header — query-param API keys are prohibited (§3.14)
             const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
-            res.json(await this.bootstrapResponse(projectPath, apiKey));
+            res.json(await this.bootstrapResponse(projectPath || this.projectPath, apiKey));
         });
         this.app.post('/api/ai-hub/api-key', (req, res) => {
             const { apiKey } = req.body;
@@ -644,9 +742,9 @@ class AiHubServer {
             this.preferencesStore.save({ ...prefs, personaKey: personaKey ?? null });
             return res.json({ ok: true });
         });
-        this.app.post('/api/ai-hub/project-path/pick', (_req, res) => {
+        this.app.post('/api/ai-hub/project-path/pick', async (_req, res) => {
             try {
-                const projectPath = pickProjectPath();
+                const projectPath = await this.folderPicker();
                 if (!projectPath) {
                     return res.status(204).end();
                 }
@@ -727,22 +825,30 @@ class AiHubServer {
             try {
                 const projectPath = ensureDirectoryPath(req.body.projectPath || this.projectPath);
                 const hostId = req.body.hostId;
-                const jobId = req.body.jobId;
-                const message = (req.body.message || '').trim();
+                const instructions = (req.body.instructions || '').trim();
+                const legacyMessage = (req.body.message || '').trim();
                 const compareMode = req.body.compareMode;
                 if (hostId !== 'codex' && hostId !== 'claude' && hostId !== 'gemini') {
                     throw new Error('Choose an available employee before starting a job.');
                 }
-                if (!jobId) {
-                    throw new Error('Choose a FRAIM job before starting a run.');
-                }
-                if (!message) {
+                if (!instructions && !legacyMessage) {
                     throw new Error('Coach your employee before starting the run.');
                 }
                 const employee = this.hostRuntime.detectEmployees().find((entry) => entry.id === hostId);
                 if (!employee?.available) {
                     throw new Error(`${employee?.label || 'Selected employee'} is not available on this machine.`);
                 }
+                const prepared = instructions
+                    ? this.prepareStartPayload(projectPath, hostId, req.body.jobId, instructions)
+                    : {
+                        jobId: req.body.jobId,
+                        message: legacyMessage,
+                    };
+                const jobId = prepared.jobId;
+                const message = prepared.message;
+                if (!jobId) {
+                    throw new Error('Choose a FRAIM job before starting a run.');
+                }
                 const startTimestamp = new Date().toISOString();
                 const run = {
                     id: (0, crypto_1.randomUUID)(),
@@ -772,7 +878,7 @@ class AiHubServer {
                 // so we can cross-link both runs via compareRunId before any events arrive.
                 // directMsg is the plain user instructions — no FRAIM invocation prefix.
                 const directMsg = compareMode === 'ab'
-                    ? ((req.body.directInstructions || '').trim() || message)
+                    ? ((req.body.directInstructions || '').trim() || instructions || message)
                     : message;
                 let directRun;
                 if (compareMode === 'ab') {
@@ -893,7 +999,16 @@ class AiHubServer {
                 if (!run.sessionId) {
                     return res.status(409).json({ error: 'This run does not have a resumable host session yet.' });
                 }
-                const message = (req.body.message || '').trim();
+                const instructions = (req.body.instructions || '').trim();
+                const coachingJobId = req.body.coachingJobId?.trim() || undefined;
+                // When coachingJobId is present (user picked a manager template via the UI),
+                // it overrides the run's own jobId in the invocation. The server always adds
+                // the correct $fraim / /fraim prefix — the UI never passes raw invocation syntax.
+                const message = instructions
+                    ? this.prepareContinueMessage(run, instructions, coachingJobId)
+                    : coachingJobId
+                        ? this.prepareContinueMessage(run, '', coachingJobId)
+                        : (req.body.message || '').trim();
                 if (!message) {
                     return res.status(400).json({ error: 'Coach your employee before sending the next turn.' });
                 }
@@ -991,6 +1106,96 @@ class AiHubServer {
             }
             return res.json(this.enrichRunForResponse(run));
         });
+        // -------------------------------------------------------------------------
+        // Issue #489: POST /api/trigger
+        // Stable API endpoint for extension surfaces (Office add-ins, browser
+        // extensions, VS Code extensions, Electron tray) to start FRAIM jobs.
+        //
+        // Body: { employeeId, jobName, context?: { text, sourceApp, fileName, ... }, projectPath? }
+        // Response: { runId, status: "started", employee, job }
+        // -------------------------------------------------------------------------
+        this.app.post('/api/trigger', (req, res) => {
+            try {
+                const { employeeId, jobName, context, projectPath: reqProjectPath } = req.body;
+                if (!employeeId) {
+                    return res.status(400).json({ error: 'employeeId is required.' });
+                }
+                if (!jobName) {
+                    return res.status(400).json({ error: 'jobName is required.' });
+                }
+                const projectPath = ensureDirectoryPath(reqProjectPath || this.projectPath);
+                // Use the requested agent directly — caller specifies which agent to run (claude, codex, gemini).
+                const employees = this.hostRuntime.detectEmployees();
+                const hostId = employeeId;
+                const employee = employees.find(e => e.id === hostId);
+                if (!employee?.available) {
+                    return res.status(503).json({ error: `${hostId} is not available on this machine.` });
+                }
+                const contextText = context?.text?.trim() || '';
+                const sourceInfo = [
+                    context?.sourceApp ? `sourceApp: ${context.sourceApp}` : '',
+                    context?.fileName ? `file: ${context.fileName}` : '',
+                ].filter(Boolean).join(', ');
+                const message = [
+                    `/fraim ${jobName}`,
+                    '',
+                    sourceInfo ? `Context (${sourceInfo}):` : 'Context:',
+                    contextText || '(no context provided)',
+                ].join('\n');
+                const startTimestamp = new Date().toISOString();
+                const run = {
+                    id: (0, crypto_1.randomUUID)(),
+                    jobId: jobName,
+                    hostId,
+                    projectPath,
+                    status: 'running',
+                    createdAt: startTimestamp,
+                    updatedAt: startTimestamp,
+                    messages: [(0, hosts_1.createHubMessage)('manager', message)],
+                    events: [(0, hosts_1.createHubEvent)('system', `Trigger: ${employeeId} / ${jobName} from ${context?.sourceApp || 'unknown'} in ${projectPath}`)],
+                    currentPhase: null,
+                    phaseHistory: [],
+                    totals: emptyTotals(),
+                    lastStatusChangeAt: startTimestamp,
+                    personaKey: getProtectedPersonaForHubJob(jobName),
+                };
+                // Register the run before spawning so onEvent/onExit callbacks can
+                // safely call update() even if they fire synchronously (FakeHostRuntime).
+                this.runRegistry.create(run, {});
+                const child = this.hostRuntime.startRun(hostId, projectPath, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            if (event.message)
+                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+                            if (event.raw)
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.seekMentoring)
+                                applySeekMentoringSignal(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
+                        });
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Trigger run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        this.runRegistry.dispose(run.id);
+                    },
+                });
+                // Update the registry entry with the real child process handle.
+                this.runRegistry.create(run, child);
+                return res.json({ runId: run.id, status: 'started', employee: employeeId, job: jobName });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not start run.' });
+            }
+        });
     }
     // Issue #347 — assemble the read-side projection of a run. Stages are
     // derived from job frontmatter + visited phases; totalDurationMs ticks
@@ -1037,8 +1242,15 @@ class AiHubServer {
 }
 exports.AiHubServer = AiHubServer;
 async function findAvailablePort(preferredPort) {
+    return findAvailablePortExcluding(preferredPort, new Set());
+}
+async function findAvailablePortExcluding(preferredPort, excludedPorts) {
     let port = preferredPort;
     while (port < preferredPort + 20) {
+        if (excludedPorts.has(port)) {
+            port += 1;
+            continue;
+        }
         const available = await new Promise((resolve) => {
             const server = net_1.default.createServer();
             server.once('error', () => resolve(false));
@@ -1066,29 +1278,64 @@ function resolveAiHubPublicDir() {
     }
     throw new Error('Could not locate public/ai-hub assets.');
 }
-function pickProjectPath() {
-    if (process.platform === 'win32') {
-        const script = [
-            'Add-Type -AssemblyName System.Windows.Forms',
-            '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
-            '$dialog.ShowNewFolderButton = $false',
-            'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
-            '  Write-Output $dialog.SelectedPath',
-            '}',
-        ].join('; ');
-        const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-Command', script], {
-            encoding: 'utf8',
-        });
-        return result.status === 0 ? result.stdout.trim() || null : null;
+// Issue #489: Resolve the word taskpane static assets directory.
+// Returns null (not throws) when the directory does not exist so the Hub
+// can start without the Word add-in assets present (e.g., older installs).
+function resolveWordTaskpaneDir(projectPath) {
+    const base = projectPath || process.cwd();
+    const candidates = [
+        path_1.default.resolve(base, 'extensions/office-word'),
+        path_1.default.resolve(__dirname, '..', '..', 'extensions/office-word'),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'extensions/office-word'),
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
     }
-    if (process.platform === 'darwin') {
-        const result = (0, child_process_1.spawnSync)('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'], {
-            encoding: 'utf8',
-        });
-        return result.status === 0 ? result.stdout.trim() || null : null;
+    // Word add-in assets not found — /word-taskpane/* routes will not be registered.
+    return null;
+}
+// Issue #478: resolve the directory that contains a named Office task pane.
+// Example: resolveTaskpaneDir('powerpoint-taskpane') → <repo>/public/ai-hub/powerpoint-taskpane
+function resolveTaskpaneDir(pane) {
+    const aiHubDir = resolveAiHubPublicDir();
+    const taskpaneDir = path_1.default.join(aiHubDir, pane);
+    if (!fs_1.default.existsSync(taskpaneDir)) {
+        throw new Error(`Task pane directory not found: ${taskpaneDir}`);
     }
-    const result = (0, child_process_1.spawnSync)('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'], {
-        encoding: 'utf8',
+    return taskpaneDir;
+}
+function pickProjectPath() {
+    return new Promise((resolve) => {
+        let cmd;
+        let args;
+        if (process.platform === 'win32') {
+            const script = [
+                'Add-Type -AssemblyName System.Windows.Forms',
+                '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+                '$dialog.ShowNewFolderButton = $false',
+                'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
+                '  Write-Output $dialog.SelectedPath',
+                '}',
+            ].join('; ');
+            cmd = 'powershell';
+            args = ['-NoProfile', '-Command', script];
+        }
+        else if (process.platform === 'darwin') {
+            cmd = 'osascript';
+            args = ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'];
+        }
+        else {
+            cmd = 'bash';
+            args = ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'];
+        }
+        let stdout = '';
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] });
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.on('close', (code) => {
+            resolve(code === 0 ? stdout.trim() || null : null);
+        });
+        child.on('error', () => resolve(null));
     });
-    return result.status === 0 ? result.stdout.trim() || null : null;
 }