@worca/ui 0.8.1 → 0.9.0-rc.2

package/server/app.js

@@ -2,26 +2,49 @@
 
 import { execFileSync } from 'node:child_process';
 import { createHmac, randomUUID } from 'node:crypto';
-import { basename, dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 
 import { dbExists, getIssue, listIssues } from './beads-reader.js';
+import { RAW_BODY } from './integrations/index.js';
+import { verify } from './integrations/verify.js';
 import { ProcessManager } from './process-manager.js';
+import { scanDirectory } from './project-registry.js';
 import {
   createProjectRoutes,
   createProjectScopedRoutes,
   projectResolver,
 } from './project-routes.js';
+import { validateIntegrationsConfig } from './settings-validator.js';
+import { discoverSubagents } from './subagents-discovery.js';
 import { getVersionInfo } from './versions.js';
 import { createInbox } from './webhook-inbox.js';
 
 export function createApp(options = {}) {
   const app = express();
   const appDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'app');
-  const { settingsPath, worcaDir, projectRoot, prefsDir } = options;
+  const {
+    settingsPath,
+    worcaDir,
+    projectRoot,
+    prefsDir,
+    serverHost,
+    serverPort,
+  } = options;
+  // subagentDirs is a test-injection seam; production calls omit it and we
+  // resolve from homedir() + projectRoot.
+  const subagentDirs = options.subagentDirs || null;
 
-  app.use(express.json());
+  app.use(
+    express.json({
+      verify: (req, _res, buf) => {
+        req.rawBody = buf;
+      },
+    }),
+  );
 
   // ─── Security headers ──────────────────────────────────────────────────
   app.use((_req, res, next) => {
@@ -87,11 +110,36 @@ export function createApp(options = {}) {
       };
       next();
     },
-    createProjectScopedRoutes(),
+    createProjectScopedRoutes({ serverHost, serverPort }),
   );
 
   // ─── Unique routes (not in project-scoped router) ──────────────────────
 
+  // GET /api/subagents — list discoverable subagent types for the dispatch editor.
+  // Walks ~/.claude/agents/ (user-global), ~/.claude/plugins/cache/
+  // (plugin-cached), and the active project's .claude/agents/ (in single-project
+  // mode). Tests inject alternate dirs via createApp({ subagentDirs: {...} }).
+  app.get('/api/subagents', (_req, res) => {
+    try {
+      const userDir =
+        subagentDirs?.userDir ?? join(homedir(), '.claude', 'agents');
+      const pluginCacheDir =
+        subagentDirs?.pluginCacheDir ??
+        join(homedir(), '.claude', 'plugins', 'cache');
+      const projectAgentsDir =
+        subagentDirs?.projectAgentsDir ??
+        (projectRoot ? join(projectRoot, '.claude', 'agents') : undefined);
+      const subagents = discoverSubagents({
+        userDir,
+        pluginCacheDir,
+        projectAgentsDir,
+      });
+      res.json({ ok: true, subagents });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
   // GET /api/beads/issues
   app.get('/api/beads/issues', (_req, res) => {
     if (!worcaDir)
@@ -250,6 +298,16 @@ export function createApp(options = {}) {
 
   // POST /api/webhooks/inbox — receive webhook events
   app.post('/api/webhooks/inbox', (req, res) => {
+    const integrations = app.locals.integrations;
+    if (integrations?.strictInboxVerification) {
+      const ok = verify(
+        req.rawBody || Buffer.alloc(0),
+        req.headers['x-worca-signature'],
+        integrations.secrets || [],
+      );
+      if (!ok)
+        return res.status(401).json({ ok: false, error: 'invalid signature' });
+    }
     const headers = {
       'x-worca-event': req.headers['x-worca-event'] || '',
       'x-worca-delivery': req.headers['x-worca-delivery'] || '',
@@ -266,9 +324,11 @@ export function createApp(options = {}) {
       envelope: req.body || {},
       projectId,
     });
+    if (req.rawBody) stored[RAW_BODY] = req.rawBody;
     if (app.locals.broadcast) {
       app.locals.broadcast('webhook-inbox-event', stored);
     }
+    app.locals.integrations?.onEvent(stored);
     res.json({ control: { action: webhookInbox.getControlAction() } });
   });
 
@@ -300,6 +360,16 @@ export function createApp(options = {}) {
 
   // PUT /api/webhooks/inbox/control — set control action
   app.put('/api/webhooks/inbox/control', (req, res) => {
+    const integrations = app.locals.integrations;
+    if (integrations?.strictInboxVerification) {
+      const ok = verify(
+        req.rawBody || Buffer.alloc(0),
+        req.headers['x-worca-signature'],
+        integrations.secrets || [],
+      );
+      if (!ok)
+        return res.status(401).json({ ok: false, error: 'invalid signature' });
+    }
     const { action } = req.body || {};
     if (!['continue', 'pause', 'abort'].includes(action)) {
       return res.status(400).json({
@@ -404,6 +474,30 @@ export function createApp(options = {}) {
     }
   });
 
+  // POST /api/scan-directory — scan parent folder for immediate git subdirectories
+  app.post('/api/scan-directory', async (req, res) => {
+    const { path: dirPath } = req.body || {};
+    if (!dirPath || typeof dirPath !== 'string') {
+      return res.status(400).json({ ok: false, error: 'path is required' });
+    }
+    if (!isAbsolute(dirPath)) {
+      return res
+        .status(400)
+        .json({ ok: false, error: 'path must be absolute' });
+    }
+    if (!existsSync(dirPath)) {
+      return res
+        .status(400)
+        .json({ ok: false, error: `directory does not exist: ${dirPath}` });
+    }
+    try {
+      const subfolders = await scanDirectory(dirPath);
+      res.json({ ok: true, subfolders });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  });
+
   // GET /api/versions — installed + registry version info
   app.get('/api/versions', async (req, res) => {
     const force = req.query.force === '1';
@@ -419,14 +513,255 @@ export function createApp(options = {}) {
 
   // ─── Multi-project routes ──────────────────────────────────────────────
   if (prefsDir) {
-    app.use('/api/projects', createProjectRoutes({ prefsDir, projectRoot }));
+    app.use(
+      '/api/projects',
+      createProjectRoutes({ prefsDir, projectRoot, serverHost, serverPort }),
+    );
     app.use(
       '/api/projects/:projectId',
       projectResolver({ prefsDir, projectRoot }),
-      createProjectScopedRoutes(),
+      createProjectScopedRoutes({ prefsDir, serverHost, serverPort }),
     );
   }
 
+  // POST /api/integrations/telegram/detect — find chat IDs from recent messages.
+  // If the Telegram adapter is running, temporarily pauses its poll loop so
+  // getUpdates returns results instead of being consumed by the long-poller.
+  app.post('/api/integrations/telegram/detect', async (req, res) => {
+    let token = req.body?.token;
+    if (!token) {
+      try {
+        const cfgRaw = readFileSync(
+          join(prefsDir, 'integrations', 'config.json'),
+          'utf8',
+        );
+        token = JSON.parse(cfgRaw).telegram?.bot_token;
+      } catch {
+        /* no config */
+      }
+    }
+    if (!token) token = process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) {
+      return res.status(400).json({ error: 'No bot token provided' });
+    }
+
+    // Pause the running adapter so getUpdates isn't consumed by the poll loop
+    const integrations = app.locals.integrations;
+    const adapterEntry = integrations?._getAdapter?.('telegram');
+    let wasStopped = false;
+    if (adapterEntry) {
+      try {
+        await adapterEntry.adapter.stop();
+        wasStopped = true;
+        // Brief delay to let the in-flight long-poll request complete
+        await new Promise((r) => setTimeout(r, 200));
+      } catch {
+        /* ignore */
+      }
+    }
+
+    try {
+      const meRes = await fetch(`https://api.telegram.org/bot${token}/getMe`);
+      const me = await meRes.json();
+      const botUsername = me.ok ? me.result.username : null;
+
+      const updRes = await fetch(
+        `https://api.telegram.org/bot${token}/getUpdates?timeout=0&limit=20`,
+      );
+      const upd = await updRes.json();
+
+      const chats = [];
+      if (upd.ok) {
+        for (const u of upd.result) {
+          const msg = u.message;
+          if (msg?.chat?.id) {
+            const existing = chats.find((c) => c.id === msg.chat.id);
+            if (!existing) {
+              chats.push({
+                id: msg.chat.id,
+                type: msg.chat.type,
+                title:
+                  msg.chat.title || msg.chat.first_name || String(msg.chat.id),
+              });
+            }
+          }
+        }
+      }
+
+      res.json({ ok: true, botUsername, chats });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    } finally {
+      // Restart the adapter if we paused it
+      if (wasStopped && adapterEntry) {
+        adapterEntry.adapter.start().catch(() => {});
+      }
+    }
+  });
+
+  // GET /api/integrations/status — adapter states, chat states, counters
+  app.get('/api/integrations/status', (_req, res) => {
+    const integrations = app.locals.integrations;
+    if (!integrations) return res.json({ enabled: false });
+    res.json(integrations.status());
+  });
+
+  // GET /api/integrations/config — return saved config (secrets redacted)
+  app.get('/api/integrations/config', (_req, res) => {
+    const configPath = join(prefsDir, 'integrations', 'config.json');
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return res.json({});
+    }
+    res.json(cfg);
+  });
+
+  // DELETE /api/integrations/config/:adapter — remove an adapter
+  // PATCH /api/integrations/config/:adapter/enabled — toggle adapter on/off
+  app.patch('/api/integrations/config/:adapter/enabled', async (req, res) => {
+    const { adapter } = req.params;
+    const { enabled } = req.body;
+    if (typeof enabled !== 'boolean') {
+      return res.status(400).json({ error: 'enabled must be a boolean' });
+    }
+    const adapterKeys = ['telegram', 'discord', 'slack'];
+    if (!adapterKeys.includes(adapter)) {
+      return res.status(400).json({ error: `Invalid adapter: ${adapter}` });
+    }
+    const configPath = join(prefsDir, 'integrations', 'config.json');
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return res.status(404).json({ error: 'No integrations config' });
+    }
+    if (!cfg[adapter]) {
+      return res
+        .status(404)
+        .json({ error: `Adapter ${adapter} not configured` });
+    }
+    cfg[adapter].enabled = enabled;
+    writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
+
+    // Hot-reload: if disabling, remove the adapter; if enabling, reload it
+    if (app.locals.ensureIntegrations) app.locals.ensureIntegrations();
+    if (enabled) {
+      if (app.locals.integrations?.reloadAdapter) {
+        await app.locals.integrations.reloadAdapter(adapter);
+      }
+    } else {
+      if (app.locals.integrations?.removeAdapter) {
+        await app.locals.integrations.removeAdapter(adapter);
+      }
+    }
+    res.json({ ok: true, enabled });
+  });
+
+  app.delete('/api/integrations/config/:adapter', async (req, res) => {
+    const { adapter } = req.params;
+    const adapterKeys = ['telegram', 'discord', 'slack'];
+    if (!adapterKeys.includes(adapter)) {
+      return res.status(400).json({ error: `Invalid adapter: ${adapter}` });
+    }
+    const configDir = join(prefsDir, 'integrations');
+    const configPath = join(configDir, 'config.json');
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch {
+      return res.json({ ok: true });
+    }
+    delete cfg[adapter];
+    const hasAdapters = adapterKeys.some((k) => cfg[k]?.enabled);
+    if (!hasAdapters) cfg.enabled = false;
+    try {
+      writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    } catch (err) {
+      return res
+        .status(500)
+        .json({ error: `Failed to write config: ${err.message}` });
+    }
+    if (app.locals.integrations?.removeAdapter) {
+      await app.locals.integrations.removeAdapter(adapter);
+    }
+    res.json({ ok: true });
+  });
+
+  // POST /api/integrations/config — save adapter config
+  const ADAPTER_SCHEMA = {
+    telegram: { tokenKey: 'bot_token', idKey: 'chat_id' },
+    discord: { tokenKey: 'bot_token', idKey: 'channel_id' },
+    slack: { tokenKey: 'webhook_url', idKey: 'chat_id' },
+  };
+
+  app.post('/api/integrations/config', async (req, res) => {
+    const { adapter, token, chatId, events } = req.body;
+    if (
+      !adapter ||
+      !token ||
+      !chatId ||
+      !Array.isArray(events) ||
+      events.length === 0
+    ) {
+      return res.status(400).json({
+        error: 'Missing required fields: adapter, token, chatId, events',
+      });
+    }
+    const schema = ADAPTER_SCHEMA[adapter];
+    if (!schema) {
+      return res.status(400).json({
+        error: `Invalid adapter: ${adapter}. Must be one of: ${Object.keys(ADAPTER_SCHEMA).join(', ')}`,
+      });
+    }
+
+    const configDir = join(prefsDir, 'integrations');
+    const configPath = join(configDir, 'config.json');
+
+    // Load existing config or start fresh
+    let cfg = { schema_version: 1, enabled: true };
+    try {
+      const raw = readFileSync(configPath, 'utf8');
+      cfg = JSON.parse(raw);
+    } catch {
+      /* start fresh */
+    }
+
+    // Build adapter block — store token directly in config
+    const adapterBlock = { enabled: true, events };
+    adapterBlock[schema.tokenKey] = token;
+    adapterBlock[schema.idKey] = chatId;
+
+    cfg[adapter] = adapterBlock;
+    cfg.enabled = true;
+    if (!cfg.schema_version) cfg.schema_version = 1;
+
+    const result = validateIntegrationsConfig(cfg);
+    if (!result.valid) {
+      return res
+        .status(400)
+        .json({ error: `Validation failed: ${result.details.join('; ')}` });
+    }
+
+    try {
+      mkdirSync(configDir, { recursive: true });
+      writeFileSync(configPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    } catch (err) {
+      return res
+        .status(500)
+        .json({ error: `Failed to write config: ${err.message}` });
+    }
+
+    // Hot-reload just this adapter (no full restart)
+    if (app.locals.ensureIntegrations) app.locals.ensureIntegrations();
+    if (app.locals.integrations?.reloadAdapter) {
+      await app.locals.integrations.reloadAdapter(adapter);
+    }
+
+    res.json({ ok: true, path: configPath });
+  });
+
   // ─── Dynamic favicon ──────────────────────────────────────────────────
   // Serve mode-specific favicon before express.static so it takes precedence.
   app.get('/favicon.svg', (_req, res) => {

package/server/dispatch-events-aggregator.js

@@ -0,0 +1,161 @@
+/**
+ * Dispatch-event aggregator — reads pipeline.hook.dispatch_{allowed,blocked}
+ * events from a run's events.jsonl and assigns them to the matching iteration
+ * in status.json by timestamp range.
+ *
+ * Works for both live and completed runs because it reads only persisted data
+ * (events.jsonl is append-only and survives the pipeline process exiting).
+ *
+ * Aggregation: events are deduplicated per iteration by (type, subagent_type).
+ * A `count` field tracks how many times the same (type, subagent_type) fired
+ * in that iteration. The `reason` from the first occurrence is kept (reasons
+ * for the same key are deterministic — derived from the denylist/rule check).
+ *
+ * Output shape per iteration:
+ *   dispatch_events: [
+ *     { type, subagent_type, reason?, count }
+ *   ]
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+const DISPATCH_EVENT_TYPES = new Set([
+  'pipeline.hook.dispatch_allowed',
+  'pipeline.hook.dispatch_blocked',
+]);
+
+/**
+ * Parse events.jsonl and return only the dispatch events, with normalised shape.
+ * Malformed lines are silently skipped so a corrupt event doesn't break the run view.
+ *
+ * @param {string} eventsPath — absolute path to events.jsonl
+ * @returns {Array<{type, subagent_type, reason?, timestamp}>}
+ */
+export function readDispatchEventsFromJsonl(eventsPath) {
+  if (!eventsPath || !existsSync(eventsPath)) return [];
+  let content;
+  try {
+    content = readFileSync(eventsPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of content.split('\n')) {
+    if (!line.trim()) continue;
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!DISPATCH_EVENT_TYPES.has(e.event_type)) continue;
+    const payload = e.payload || {};
+    if (!payload.subagent_type) continue;
+    out.push({
+      type: e.event_type,
+      subagent_type: payload.subagent_type,
+      reason: payload.reason,
+      timestamp: e.timestamp,
+    });
+  }
+  return out;
+}
+
+/**
+ * Given a list of dispatch events and a stages map from status.json, return
+ * a new stages map where each iteration that overlaps an event's timestamp
+ * is enriched with a `dispatch_events` array (deduplicated by type+subagent_type
+ * with a count).
+ *
+ * Non-destructive: input stages object is shallow-copied; iterations get new
+ * objects with the extra field. Existing iteration fields are preserved.
+ *
+ * @param {Array<{type, subagent_type, reason?, timestamp}>} events
+ * @param {object} stages — status.stages
+ * @returns {object} enriched stages
+ */
+export function assignEventsToIterations(events, stages) {
+  if (!stages || typeof stages !== 'object') return stages;
+  if (!events || events.length === 0) {
+    // Nothing to add — return input unchanged to avoid unnecessary allocation.
+    return stages;
+  }
+
+  // Bucket events into iterations first, then aggregate per bucket.
+  // Bucket key: `${stageKey}|${iterationNumber}`.
+  const buckets = new Map();
+
+  for (const ev of events) {
+    if (!ev.timestamp) continue;
+    const eventTime = Date.parse(ev.timestamp);
+    if (Number.isNaN(eventTime)) continue;
+
+    let matched = false;
+    for (const [stageKey, stage] of Object.entries(stages)) {
+      const iterations = stage?.iterations;
+      if (!Array.isArray(iterations)) continue;
+      for (const iter of iterations) {
+        const start = iter.started_at ? Date.parse(iter.started_at) : NaN;
+        if (Number.isNaN(start)) continue;
+        // If the iteration hasn't completed, treat end as +infinity so live events land here.
+        const end = iter.completed_at
+          ? Date.parse(iter.completed_at)
+          : Number.POSITIVE_INFINITY;
+        if (eventTime >= start && eventTime <= end) {
+          const key = `${stageKey}|${iter.number}`;
+          if (!buckets.has(key)) buckets.set(key, []);
+          buckets.get(key).push(ev);
+          matched = true;
+          break;
+        }
+      }
+      if (matched) break;
+    }
+    // If no iteration matched, the event is silently dropped — it falls
+    // outside any recorded iteration window (e.g. during stage transitions).
+  }
+
+  if (buckets.size === 0) return stages;
+
+  // Aggregate each bucket and build the enriched stages map.
+  const enrichedStages = { ...stages };
+  for (const [key, bucketEvents] of buckets) {
+    const [stageKey, iterNumStr] = key.split('|');
+    const iterNum = Number(iterNumStr);
+    const stage = enrichedStages[stageKey];
+    if (!stage) continue;
+    const aggregated = aggregate(bucketEvents);
+    const newIterations = stage.iterations.map((iter) =>
+      iter.number === iterNum ? { ...iter, dispatch_events: aggregated } : iter,
+    );
+    enrichedStages[stageKey] = { ...stage, iterations: newIterations };
+  }
+  return enrichedStages;
+}
+
+/**
+ * Deduplicate an array of dispatch events by (type, subagent_type) and count
+ * occurrences. First reason wins for blocked events.
+ *
+ * @param {Array<{type, subagent_type, reason?}>} events
+ * @returns {Array<{type, subagent_type, reason?, count}>}
+ */
+function aggregate(events) {
+  const map = new Map();
+  for (const ev of events) {
+    const key = `${ev.type}|${ev.subagent_type}`;
+    const existing = map.get(key);
+    if (existing) {
+      existing.count += 1;
+    } else {
+      const entry = {
+        type: ev.type,
+        subagent_type: ev.subagent_type,
+        count: 1,
+      };
+      if (ev.reason) entry.reason = ev.reason;
+      map.set(key, entry);
+    }
+  }
+  return [...map.values()];
+}

package/server/ensure-webhook.js

@@ -0,0 +1,66 @@
+// ensure-webhook.js — auto-configure a webhook pointing to this worca-ui instance
+// in a project's settings.local.json so the pipeline sends events to the UI.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { localPathFor } from './settings-merge.js';
+
+/**
+ * Ensure a webhook entry exists in the project's settings.local.json
+ * pointing to the worca-ui inbox at the given host:port.
+ *
+ * Skips if a webhook for this host:port already exists.
+ * Creates settings.local.json if it doesn't exist.
+ *
+ * @param {string} projectPath — absolute path to the project root
+ * @param {{ host: string, port: number }} server — worca-ui server address
+ */
+export function ensureWebhookForUi(projectPath, { host, port }) {
+  const settingsPath = join(projectPath, '.claude', 'settings.json');
+  const localPath = localPathFor(settingsPath);
+  // Use localhost instead of 127.0.0.1 — the pipeline validator only allows
+  // https:// or http://localhost for security.
+  const displayHost =
+    host === '127.0.0.1' || host === '::1' ? 'localhost' : host;
+  const inboxUrl = `http://${displayHost}:${port}/api/webhooks/inbox`;
+
+  // Read existing local settings (or start fresh)
+  let local = {};
+  if (existsSync(localPath)) {
+    try {
+      local = JSON.parse(readFileSync(localPath, 'utf8'));
+    } catch {
+      local = {};
+    }
+  }
+
+  if (!local.worca) local.worca = {};
+  if (!Array.isArray(local.worca.webhooks)) local.worca.webhooks = [];
+
+  // Check if a webhook for this URL already exists
+  const exists = local.worca.webhooks.some((wh) => wh.url === inboxUrl);
+  if (exists) return false;
+
+  // Also check base settings.json (in case it was manually configured there)
+  try {
+    const base = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    const baseWebhooks = base?.worca?.webhooks || [];
+    if (baseWebhooks.some((wh) => wh.url === inboxUrl)) return false;
+  } catch {
+    // no base settings — proceed
+  }
+
+  local.worca.webhooks.push({
+    url: inboxUrl,
+    events: ['pipeline.*'],
+  });
+
+  // Ensure events are enabled
+  if (!local.worca.events) local.worca.events = {};
+  if (local.worca.events.enabled === undefined) {
+    local.worca.events.enabled = true;
+  }
+
+  writeFileSync(localPath, `${JSON.stringify(local, null, 2)}\n`, 'utf8');
+  return true;
+}

package/server/index.js

@@ -4,6 +4,7 @@ import { createServer } from 'node:http';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import { createApp } from './app.js';
+import { createIntegrations } from './integrations/index.js';
 import { attachWsServer } from './ws.js';
 
 // Parse argv
@@ -57,6 +58,8 @@ const app = createApp({
   projectRoot,
   webhookInbox,
   prefsDir,
+  serverHost: host,
+  serverPort: port,
 });
 const server = createServer(app);
 
@@ -104,6 +107,25 @@ app.locals.broadcast = broadcast;
 app.locals.scheduleRefresh = scheduleRefresh;
 app.locals.resolveRunProject = resolveRunProject;
 
+// Boot chat integrations only in global mode — project-scoped instances skip
+// integrations to avoid duplicate Telegram long-poll connections on the same bot.
+if (isGlobal) {
+  const integrationsOpts = {
+    port,
+    host,
+    prefsDir,
+    configPath: join(prefsDir, 'integrations', 'config.json'),
+  };
+  app.locals.integrations = createIntegrations(integrationsOpts);
+  app.locals.ensureIntegrations = () => {
+    if (!app.locals.integrations?.reloadAdapter) {
+      app.locals.integrations = createIntegrations(integrationsOpts);
+    }
+  };
+} else {
+  console.log('[integrations] Skipped — integrations only run in global mode');
+}
+
 // ─── worca-cc version check (non-blocking) ─────────────────────────────
 checkWorcaVersion().then((result) => {
   app.locals.worcaVersion = result;