fraim 2.0.165 → 2.0.167

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

@@ -13,29 +13,23 @@ exports.getAiHubCategories = getAiHubCategories;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
-// Directories scanned for employee jobs, in lowest-to-highest precedence
-// order. Later entries win on {categoryId, jobId} collision. All present
-// layers contribute their category structure.
+// Directories scanned for employee jobs at runtime, in lowest-to-highest
+// precedence order. Later entries win on {categoryId, jobId} collision.
 //
-// Each entry is `[base, ...segments]` resolved relative to the project root:
-//   - 'registry'       → <project>/registry/jobs/ai-employee/<category>/
-//                        (present in the FRAIM source repo and in dist/)
-//   - 'fraim'          → <project>/fraim/ai-employee/jobs/<category>/
-//                        (the baseline synced into a regular project via
-//                        `fraim setup` / `fraim sync`)
-//   - 'fraim'          → <project>/fraim/personalized-employee/jobs/<category>/
-//                        (per-project override layer; CLAUDE.md says it
-//                        "takes precedence over synced baseline content")
+// FRAIM execution only ever reads the two `fraim/` layers — the synced baseline
+// and the personalized override. (`registry/` is a development-only source tree,
+// never read at runtime; jobs reach a project via sync into `fraim/ai-employee`.)
+//   - <project>/fraim/ai-employee/jobs/<category>/        — synced baseline (shared)
+//   - <project>/fraim/personalized-employee/jobs/<category>/ — taught/customized override
+// Only the personalized-employee layer is "personalized" (issue #566).
 const EMPLOYEE_JOB_LAYERS = [
-    { base: 'registry', segments: ['jobs', 'ai-employee'] },
-    { base: 'fraim', segments: ['ai-employee', 'jobs'] },
-    { base: 'fraim', segments: ['personalized-employee', 'jobs'] },
+    { segments: ['ai-employee', 'jobs'], personalized: false },
+    { segments: ['personalized-employee', 'jobs'], personalized: true },
 ];
-// Manager templates use the matching two-layer model.
+// Manager templates use the matching layer model.
 const MANAGER_JOB_LAYERS = [
-    { base: 'registry', segments: ['jobs', 'ai-manager'] },
-    { base: 'fraim', segments: ['ai-manager', 'jobs'] },
-    { base: 'fraim', segments: ['personalized-employee', 'manager-jobs'] },
+    { segments: ['ai-manager', 'jobs'], personalized: false },
+    { segments: ['personalized-employee', 'manager-jobs'], personalized: true },
 ];
 const KNOWN_LABEL_OVERRIDES = {
     // Project conventions where a directory name should render as a recognized
@@ -93,7 +87,7 @@ function readMarkdownFileNames(dirPath) {
         .map((entry) => entry.name)
         .sort((a, b) => a.localeCompare(b));
 }
-function parseJobStub(filePath, categoryId, categoryLabel, projectPath) {
+function parseJobStub(filePath, categoryId, categoryLabel, projectPath, personalized) {
     const content = fs_1.default.readFileSync(filePath, 'utf8');
     const fileName = path_1.default.basename(filePath, '.md');
     const intent = sectionValue(content, 'Intent')[0] || 'No intent summary available.';
@@ -106,6 +100,7 @@ function parseJobStub(filePath, categoryId, categoryLabel, projectPath) {
         intent,
         outcome,
         stubPath: toPosix(path_1.default.relative(projectPath, filePath)),
+        personalized: !!personalized,
     };
 }
 function parseManagerStub(filePath, groupId, groupLabel, projectPath) {
@@ -139,8 +134,7 @@ function summarizeProject(projectPath) {
         };
     }
     const fraimDir = (0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath);
-    const registryJobsDir = path_1.default.join(projectPath, 'registry', 'jobs');
-    const hasFraim = fs_1.default.existsSync(fraimDir) || fs_1.default.existsSync(registryJobsDir);
+    const hasFraim = fs_1.default.existsSync(fraimDir);
     if (!hasFraim) {
         return {
             path: projectPath,
@@ -157,9 +151,6 @@ function summarizeProject(projectPath) {
     };
 }
 function resolveLayerRoot(projectPath, layer) {
-    if (layer.base === 'registry') {
-        return path_1.default.join(projectPath, 'registry', ...layer.segments);
-    }
     return path_1.default.join((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath), ...layer.segments);
 }
 function discoverLayers(projectPath, layers) {
@@ -171,6 +162,7 @@ function discoverLayers(projectPath, layers) {
                 layerRoot,
                 categoryId: categoryName,
                 categoryDir: path_1.default.join(layerRoot, categoryName),
+                personalized: layer.personalized,
             });
         }
     }
@@ -187,9 +179,10 @@ function discoverEmployeeJobs(projectPath) {
         const categoryLabel = humanizeName(layer.categoryId);
         for (const fileName of readMarkdownFileNames(layer.categoryDir)) {
             const filePath = path_1.default.join(layer.categoryDir, fileName);
-            const job = parseJobStub(filePath, layer.categoryId, categoryLabel, projectPath);
+            const job = parseJobStub(filePath, layer.categoryId, categoryLabel, projectPath, layer.personalized);
             // Later layers override earlier layers on {category, jobId} collision —
-            // personalized-employee wins over the synced ai-employee baseline.
+            // personalized-employee wins over the synced ai-employee baseline. The
+            // winning job carries its own layer's `personalized` flag (issue #566).
             jobsByKey.set(`${job.categoryId}::${job.id}`, job);
         }
     }

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

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AiHubServer = void 0;
+exports.AiHubServer = exports.HostConfigStore = exports.DeploymentStore = void 0;
 exports.findAvailablePort = findAvailablePort;
 exports.findAvailablePortExcluding = findAvailablePortExcluding;
 const express_1 = __importDefault(require("express"));
@@ -180,6 +180,113 @@ function safeHttpUrl(value) {
         return null;
     }
 }
+// ─── Issue #578: Deployment + Host stores ─────────────────────────────────────
+class DeploymentStore {
+    constructor(filePath) {
+        this.filePath = filePath ?? path_1.default.join(getUserHubDir(), 'hub-deployments.json');
+    }
+    load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath))
+                return [];
+            return JSON.parse(fs_1.default.readFileSync(this.filePath, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    save(deployments) {
+        fs_1.default.mkdirSync(path_1.default.dirname(this.filePath), { recursive: true });
+        fs_1.default.writeFileSync(this.filePath, JSON.stringify(deployments, null, 2));
+    }
+    create(deployment) {
+        const list = this.load();
+        list.push(deployment);
+        this.save(list);
+        return deployment;
+    }
+    update(id, updater) {
+        const list = this.load();
+        const dep = list.find((d) => d.id === id);
+        if (!dep)
+            return false;
+        updater(dep);
+        dep.updatedAt = new Date().toISOString();
+        this.save(list);
+        return true;
+    }
+    delete(id) {
+        const list = this.load();
+        const next = list.filter((d) => d.id !== id);
+        if (next.length === list.length)
+            return false;
+        this.save(next);
+        return true;
+    }
+}
+exports.DeploymentStore = DeploymentStore;
+class HostConfigStore {
+    constructor(filePath) {
+        this.filePath = filePath ?? path_1.default.join(getUserHubDir(), 'hub-hosts.json');
+    }
+    load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath))
+                return [];
+            return JSON.parse(fs_1.default.readFileSync(this.filePath, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    save(hosts) {
+        fs_1.default.mkdirSync(path_1.default.dirname(this.filePath), { recursive: true });
+        fs_1.default.writeFileSync(this.filePath, JSON.stringify(hosts, null, 2));
+    }
+    add(host) {
+        const list = this.load();
+        list.push(host);
+        this.save(list);
+        return host;
+    }
+    delete(id) {
+        const list = this.load();
+        const next = list.filter((h) => h.id !== id);
+        if (next.length === list.length)
+            return false;
+        this.save(next);
+        return true;
+    }
+}
+exports.HostConfigStore = HostConfigStore;
+async function pingHost(host) {
+    const start = Date.now();
+    try {
+        const resp = await fetch(`${host.url.replace(/\/$/, '')}/health`, {
+            signal: AbortSignal.timeout(5000),
+            headers: host.authToken ? { 'X-Hub-Auth': host.authToken } : {},
+        });
+        const latencyMs = Date.now() - start;
+        return {
+            id: host.id,
+            label: host.label,
+            url: host.url,
+            status: resp.ok ? 'online' : 'degraded',
+            latencyMs,
+            lastPingAt: new Date().toISOString(),
+        };
+    }
+    catch {
+        return {
+            id: host.id,
+            label: host.label,
+            url: host.url,
+            status: 'offline',
+            latencyMs: null,
+            lastPingAt: new Date().toISOString(),
+        };
+    }
+}
 function normalizeReviewArtifact(raw, index = 0) {
     if (!raw || typeof raw !== 'object')
         return null;
@@ -748,6 +855,7 @@ class AiHubServer {
     constructor(options = {}) {
         this.app = (0, express_1.default)();
         this.runRegistry = new AiHubRunRegistry();
+        this.cronHandles = new Map();
         this.projectPath = options.projectPath || process.cwd();
         this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
         this.conversationStore = options.conversationStore || new conversation_store_1.AiHubConversationStore();
@@ -770,7 +878,9 @@ class AiHubServer {
             this.dbService = createDefaultDbService();
             this.ownsDbService = this.dbService !== undefined;
         }
-        this.app.use(express_1.default.json());
+        this.deploymentStore = options.deploymentStore ?? new DeploymentStore();
+        this.hostConfigStore = options.hostConfigStore ?? new HostConfigStore();
+        this.app.use(express_1.default.json({ limit: '10mb' }));
         if (this.dbService) {
             const { registerPaymentRoutes } = require('../routes/payment-routes');
             registerPaymentRoutes(this.app, () => this.paymentRepo ?? null, this.dbService);
@@ -914,6 +1024,8 @@ class AiHubServer {
         // so it's known even before the browser is running.
         process.env.FRAIM_BROWSER_CDP_ENDPOINT = this.managedBrowser.cdpEndpoint();
         process.env.FRAIM_HUB_BASE_URL = `http://127.0.0.1:${port}`;
+        // Issue #578: rehydrate active scheduled deployments from disk.
+        this.rehydrateScheduledDeployments();
         // 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.
@@ -953,6 +1065,11 @@ class AiHubServer {
             await closeServer(this.httpServer);
             this.httpServer = undefined;
         }
+        // Issue #578: stop all active scheduled deployments.
+        for (const [, task] of this.cronHandles) {
+            task.stop();
+        }
+        this.cronHandles.clear();
         // #521: tear down the shared browser if WE launched it (stop() no-ops on a
         // browser the manager owns).
         this.managedBrowser.stop();
@@ -978,6 +1095,9 @@ class AiHubServer {
         }
         const project = (0, catalog_1.summarizeProject)(normalizedProjectPath);
         const rawJobs = (0, catalog_1.discoverEmployeeJobs)(normalizedProjectPath);
+        // Issue #566 (R7): jobs already carry `personalized` from catalog discovery
+        // (true for the fraim/personalized-employee layer). The Hub renders a plain
+        // "Personalized" marking from that flag — no author/attribution is tracked.
         const jobs = rawJobs.map((job) => ({
             ...job,
             requiredPersonaKey: getProtectedPersonaForHubJob(job.id),
@@ -1045,6 +1165,8 @@ class AiHubServer {
             reviewHandoff: run.reviewHandoff || null,
             compareMode: run.runRole === 'fraim' && run.compareRunId ? 'ab' : undefined,
             compareRunId: run.compareRunId || null,
+            // Issue #578: preserve trigger source so the UI can render the chip.
+            sourceTrigger: run.sourceTrigger,
         };
     }
     persistRunConversation(run, activeId) {
@@ -1718,6 +1840,8 @@ class AiHubServer {
                     personaKey: getProtectedPersonaForHubJob(jobId),
                     // Issue #442: mark this as the FRAIM side of an A/B pair when applicable.
                     ...(compareMode === 'ab' ? { runRole: 'fraim' } : {}),
+                    // #0: trigger source — defaults to 'manager' when not provided by the caller.
+                    sourceTrigger: req.body.sourceTrigger ?? 'manager',
                 };
                 this.runRegistry.create(run, {});
                 this.persistRunConversation(run, run.conversationId || run.id);
@@ -2111,6 +2235,42 @@ class AiHubServer {
                 res.status(400).json({ error: error instanceof Error ? error.message : 'Could not continue Direct run.' });
             }
         });
+        // GET /api/ai-hub/runs — list runs for cross-host polling and the UI ledger.
+        // Query params: status (filter), sourceTrigger (filter), limit (default 100, max 200).
+        // Must be registered BEFORE the :runId route to avoid 'runs' being matched as a runId.
+        this.app.get('/api/ai-hub/runs', (req, res) => {
+            const statusFilter = typeof req.query.status === 'string' ? req.query.status : null;
+            const triggerFilter = typeof req.query.sourceTrigger === 'string' ? req.query.sourceTrigger : null;
+            const limit = Math.min(200, parseInt(String(req.query.limit || '100'), 10) || 100);
+            let runs = this.runRegistry.all();
+            if (statusFilter)
+                runs = runs.filter((r) => r.status === statusFilter);
+            if (triggerFilter)
+                runs = runs.filter((r) => (r.sourceTrigger ?? 'manager') === triggerFilter);
+            runs = runs.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).slice(0, limit);
+            return res.json(runs.map((r) => this.enrichRunForResponse(r)));
+        });
+        // ─── Issue #578: /api/ai-hub/runs/merged must be registered BEFORE :runId ──
+        this.app.get('/api/ai-hub/runs/merged', async (req, res) => {
+            const local = this.runRegistry.all().map((r) => this.enrichRunForResponse(r));
+            const hosts = this.hostConfigStore.load();
+            const remoteResults = await Promise.allSettled(hosts.map(async (host) => {
+                const url = `${host.url.replace(/\/$/, '')}/api/ai-hub/runs`;
+                const resp = await fetch(url, {
+                    signal: AbortSignal.timeout(8000),
+                    headers: host.authToken ? { 'X-Hub-Auth': host.authToken } : {},
+                });
+                if (!resp.ok)
+                    return [];
+                return resp.json();
+            }));
+            const remote = remoteResults
+                .filter((r) => r.status === 'fulfilled')
+                .flatMap((r) => r.value);
+            const merged = [...local, ...remote].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+            return res.json(merged);
+        });
+        // GET /api/ai-hub/runs/:runId — registered AFTER /merged to avoid shadowing.
         this.app.get('/api/ai-hub/runs/:runId', (req, res) => {
             const run = this.runRegistry.get(req.params.runId);
             if (!run) {
@@ -2118,6 +2278,151 @@ class AiHubServer {
             }
             return res.json(this.enrichRunForResponse(run));
         });
+        // ─── Issue #578: Scheduled + Reactive Employees ───────────────────────────
+        // POST /api/ai-hub/schedules — create a recurring scheduled deployment.
+        this.app.post('/api/ai-hub/schedules', (req, res) => {
+            const { label, jobId, projectPath, hostId, cronExpr, instructions, outputChannel, allowConcurrent } = req.body ?? {};
+            if (!label || !jobId || !cronExpr) {
+                return res.status(400).json({ error: 'label, jobId, and cronExpr are required.' });
+            }
+            const validEmployees = ['codex', 'claude', 'gemini', 'copilot'];
+            const resolvedHostId = validEmployees.includes(hostId) ? hostId : 'claude';
+            const now = new Date().toISOString();
+            const deployment = {
+                id: (0, crypto_1.randomUUID)(),
+                type: 'scheduled',
+                label,
+                jobId,
+                projectPath: ensureDirectoryPath(projectPath || this.projectPath),
+                hostId: resolvedHostId,
+                cronExpr,
+                instructions: typeof instructions === 'string' ? instructions : undefined,
+                outputChannel: typeof outputChannel === 'string' ? outputChannel : undefined,
+                allowConcurrent: allowConcurrent === true,
+                active: true,
+                createdAt: now,
+                updatedAt: now,
+            };
+            this.deploymentStore.create(deployment);
+            this.scheduleDeployment(deployment);
+            return res.status(201).json(deployment);
+        });
+        // GET /api/ai-hub/schedules — list all scheduled deployments.
+        this.app.get('/api/ai-hub/schedules', (_req, res) => {
+            return res.json(this.deploymentStore.load().filter((d) => d.type === 'scheduled'));
+        });
+        // DELETE /api/ai-hub/schedules/:id — remove a scheduled deployment.
+        this.app.delete('/api/ai-hub/schedules/:id', (req, res) => {
+            const { id } = req.params;
+            const task = this.cronHandles.get(id);
+            if (task) {
+                task.stop();
+                this.cronHandles.delete(id);
+            }
+            const deleted = this.deploymentStore.delete(id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Deployment not found.' });
+            return res.json({ ok: true });
+        });
+        // POST /api/ai-hub/webhooks — register an inbound webhook deployment.
+        this.app.post('/api/ai-hub/webhooks', (req, res) => {
+            const { label, jobId, projectPath, hostId, instructions, outputChannel, allowConcurrent } = req.body ?? {};
+            if (!label || !jobId) {
+                return res.status(400).json({ error: 'label and jobId are required.' });
+            }
+            const validEmployees = ['codex', 'claude', 'gemini', 'copilot'];
+            const resolvedHostId = validEmployees.includes(hostId) ? hostId : 'claude';
+            const now = new Date().toISOString();
+            const deployment = {
+                id: (0, crypto_1.randomUUID)(),
+                type: 'webhook',
+                label,
+                jobId,
+                projectPath: ensureDirectoryPath(projectPath || this.projectPath),
+                hostId: resolvedHostId,
+                instructions: typeof instructions === 'string' ? instructions : undefined,
+                outputChannel: typeof outputChannel === 'string' ? outputChannel : undefined,
+                allowConcurrent: allowConcurrent === true,
+                active: true,
+                createdAt: now,
+                updatedAt: now,
+            };
+            this.deploymentStore.create(deployment);
+            const hubBase = process.env.FRAIM_HUB_BASE_URL || `http://127.0.0.1:${this.httpPort}`;
+            return res.status(201).json({ ...deployment, inboundUrl: `${hubBase}/api/ai-hub/webhooks/${deployment.id}/inbound` });
+        });
+        // GET /api/ai-hub/webhooks — list all webhook deployments.
+        this.app.get('/api/ai-hub/webhooks', (_req, res) => {
+            const hubBase = process.env.FRAIM_HUB_BASE_URL || `http://127.0.0.1:${this.httpPort}`;
+            return res.json(this.deploymentStore.load()
+                .filter((d) => d.type === 'webhook')
+                .map((d) => ({ ...d, inboundUrl: `${hubBase}/api/ai-hub/webhooks/${d.id}/inbound` })));
+        });
+        // DELETE /api/ai-hub/webhooks/:id — remove a webhook deployment.
+        this.app.delete('/api/ai-hub/webhooks/:id', (req, res) => {
+            const deleted = this.deploymentStore.delete(req.params.id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Deployment not found.' });
+            return res.json({ ok: true });
+        });
+        // POST /api/ai-hub/webhooks/:id/inbound — webhook inbound trigger from external systems.
+        this.app.post('/api/ai-hub/webhooks/:id/inbound', async (req, res) => {
+            const deployments = this.deploymentStore.load();
+            const deployment = deployments.find((d) => d.id === req.params.id && d.type === 'webhook' && d.active);
+            if (!deployment) {
+                return res.status(404).json({ error: 'Webhook not found or inactive.' });
+            }
+            try {
+                const run = await this.fireDeploymentRun(deployment, req.body);
+                return res.status(202).json({ runId: run.id, status: run.status });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : 'Failed to start run.';
+                return res.status(500).json({ error: msg });
+            }
+        });
+        // GET /api/ai-hub/hosts — list registered remote hosts with health status.
+        this.app.get('/api/ai-hub/hosts', async (_req, res) => {
+            const hosts = this.hostConfigStore.load();
+            const healthResults = await Promise.allSettled(hosts.map((h) => pingHost(h)));
+            const health = healthResults.map((r, i) => r.status === 'fulfilled'
+                ? r.value
+                : { id: hosts[i].id, label: hosts[i].label, url: hosts[i].url, status: 'offline', latencyMs: null, lastPingAt: new Date().toISOString() });
+            return res.json(health);
+        });
+        // POST /api/ai-hub/hosts — register a named remote hub host.
+        this.app.post('/api/ai-hub/hosts', (req, res) => {
+            const { label, url, authToken } = req.body ?? {};
+            const validUrl = safeHttpUrl(url);
+            if (!label || !validUrl) {
+                return res.status(400).json({ error: 'label and a valid http(s) url are required.' });
+            }
+            const host = {
+                id: (0, crypto_1.randomUUID)(),
+                label,
+                url: validUrl,
+                authToken: typeof authToken === 'string' && authToken ? authToken : undefined,
+                createdAt: new Date().toISOString(),
+            };
+            this.hostConfigStore.add(host);
+            return res.status(201).json({ id: host.id, label: host.label, url: host.url, createdAt: host.createdAt });
+        });
+        // DELETE /api/ai-hub/hosts/:id — remove a named remote host.
+        this.app.delete('/api/ai-hub/hosts/:id', (req, res) => {
+            const deleted = this.hostConfigStore.delete(req.params.id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Host not found.' });
+            return res.json({ ok: true });
+        });
+        // GET /api/ai-hub/hosts/:id/health — ping a single host.
+        this.app.get('/api/ai-hub/hosts/:id/health', async (req, res) => {
+            const host = this.hostConfigStore.load().find((h) => h.id === req.params.id);
+            if (!host)
+                return res.status(404).json({ error: 'Host not found.' });
+            const health = await pingHost(host);
+            return res.json(health);
+        });
+        // ─── End Issue #578 ───────────────────────────────────────────────────────
         // -------------------------------------------------------------------------
         // Issue #489: POST /api/trigger
         // Stable API endpoint for extension surfaces (Office add-ins, browser
@@ -2216,6 +2521,117 @@ class AiHubServer {
         process.env.FRAIM_BROWSER_CDP_ENDPOINT = result.endpoint;
         return { endpoint: result.endpoint, reused: result.reused, channel: result.channel };
     }
+    // ─── Issue #578: Scheduled deployment helpers ─────────────────────────────
+    rehydrateScheduledDeployments() {
+        const deployments = this.deploymentStore.load();
+        for (const dep of deployments) {
+            if (dep.type === 'scheduled' && dep.active) {
+                this.scheduleDeployment(dep);
+            }
+        }
+        if (deployments.filter((d) => d.type === 'scheduled' && d.active).length > 0) {
+            console.log(`[ai-hub] rehydrated ${deployments.filter((d) => d.type === 'scheduled' && d.active).length} scheduled deployment(s)`);
+        }
+    }
+    scheduleDeployment(deployment) {
+        if (!deployment.cronExpr)
+            return;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const cron = require('node-cron');
+            if (!cron.validate(deployment.cronExpr)) {
+                console.warn(`[ai-hub] invalid cronExpr for deployment ${deployment.id}: ${deployment.cronExpr}`);
+                return;
+            }
+            const task = cron.schedule(deployment.cronExpr, async () => {
+                try {
+                    await this.fireDeploymentRun(deployment);
+                }
+                catch (err) {
+                    console.warn(`[ai-hub] scheduled deployment ${deployment.id} fire failed:`, err);
+                }
+            });
+            this.cronHandles.set(deployment.id, task);
+        }
+        catch (err) {
+            console.warn('[ai-hub] node-cron not available — scheduled deployments require node-cron:', err);
+        }
+    }
+    async fireDeploymentRun(deployment, webhookBody) {
+        // Overlapping run guard: if the prior run is still active and allowConcurrent is false, skip.
+        if (!deployment.allowConcurrent && deployment.activeRunId) {
+            const active = this.runRegistry.get(deployment.activeRunId);
+            if (active && active.status === 'running') {
+                console.log(`[ai-hub] deployment ${deployment.id} skipped — prior run ${deployment.activeRunId} still running`);
+                return active;
+            }
+        }
+        const employees = this.hostRuntime.detectEmployees();
+        const employee = employees.find((e) => e.id === deployment.hostId);
+        if (!employee?.available) {
+            throw new Error(`Employee ${deployment.hostId} is not available for scheduled/webhook run.`);
+        }
+        const instructions = [
+            deployment.instructions ?? `/fraim ${deployment.jobId}`,
+            webhookBody ? `\n\nInbound payload:\n${JSON.stringify(webhookBody, null, 2)}` : '',
+        ].join('').trim();
+        const startTimestamp = new Date().toISOString();
+        const run = {
+            id: (0, crypto_1.randomUUID)(),
+            jobId: deployment.jobId,
+            hostId: deployment.hostId,
+            projectPath: deployment.projectPath,
+            status: 'running',
+            sourceTrigger: deployment.type === 'scheduled' ? 'scheduled' : 'webhook',
+            createdAt: startTimestamp,
+            updatedAt: startTimestamp,
+            messages: [(0, hosts_1.createHubMessage)('manager', instructions)],
+            events: [(0, hosts_1.createHubEvent)('system', `Triggered by deployment: ${deployment.label} (${deployment.type})`)],
+            currentPhase: null,
+            phaseHistory: [],
+            totals: emptyTotals(),
+            lastStatusChangeAt: startTimestamp,
+            personaKey: getProtectedPersonaForHubJob(deployment.jobId),
+        };
+        const child = this.hostRuntime.startRun(deployment.hostId, deployment.projectPath, instructions, {
+            onEvent: (event, channel) => {
+                this.runRegistry.update(run.id, (current) => {
+                    if (event.sessionId)
+                        current.sessionId = event.sessionId;
+                    appendHostMessage(current, deployment.hostId, event, channel);
+                    if (event.raw) {
+                        current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        applyReviewProjection(current, event.raw);
+                    }
+                    if (event.agentIdentity)
+                        applyAgentIdentitySignal(current, event.agentIdentity);
+                    if (event.seekMentoring)
+                        applySeekMentoringSignal(current, event.seekMentoring);
+                    if (event.usage)
+                        applyUsageSignal(current, event.usage);
+                });
+                const updated = this.runRegistry.get(run.id);
+                if (updated)
+                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+            },
+            onExit: (exitCode) => {
+                this.runRegistry.update(run.id, (r) => {
+                    r.exitCode = exitCode;
+                    r.status = exitCode === 0 ? 'completed' : 'failed';
+                    r.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                });
+                const updated = this.runRegistry.get(run.id);
+                if (updated)
+                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+                this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = undefined; });
+                this.runRegistry.dispose(run.id);
+            },
+        });
+        this.runRegistry.create(run, child);
+        this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = run.id; });
+        return run;
+    }
+    // ─── End Issue #578 helpers ───────────────────────────────────────────────
     // Issue #347 — assemble the read-side projection of a run. Stages are
     // derived from job frontmatter + visited phases; totalDurationMs ticks
     // forward while the run is still running so the UI's totals line