yaml-flow 5.2.5 → 5.2.8

package/README.md

@@ -263,14 +263,14 @@ settings:
 
 tasks:
   fetch_sources:
-    provides: [raw-sources]
+    provides: [raw-asources]
 
   analyse_sentiment:
-    requires: [raw-sources]
+    requires: [raw-asources]
     provides: [sentiment-result]
 
   analyse_entities:
-    requires: [raw-sources]
+    requires: [raw-asources]
     provides: [entity-result]
 
   merge_analysis:
@@ -384,7 +384,7 @@ When multiple eligible tasks produce the same output token, only one should run
 
 ### Pattern: AI Agent Tool Orchestration (Event Graph)
 
-An agent needs to gather evidence from multiple sources, then synthesize.
+An agent needs to gather evidence from multiple source_defs, then synthesize.
 
 ```yaml
 settings:
@@ -735,7 +735,7 @@ Templates first (expands references), then variables (fills in `${...}` placehol
 ```typescript
 import { resolveConfigTemplates, resolveVariables } from 'yaml-flow/config';
 
-const raw = loadYaml('pipeline.yaml');                  // has configTemplates + ${VAR} refs
+const raw = loadYaml('pipeline.yaml');                  // has configTemplates + ${VAR} projections
 const resolved = resolveVariables(
   resolveConfigTemplates(raw),
   { ENTITY_ID: 'url-42', TOOLS_DIR: '/opt/tools' },
@@ -971,7 +971,7 @@ const r3 = validateLiveCardSchema(config);
 |---|---|---|
 | `validateGraphSchema` | `schema/event-graph.schema.json` | Tasks, settings, refreshStrategy, retry, circuit_breaker, inference hints |
 | `validateFlowSchema` | `schema/flow.schema.json` | Steps, transitions, retry, terminal states |
-| `validateLiveCardSchema` | `schema/live-cards.schema.json` | Cards, sources, elements, compute, data bindings |
+| `validateLiveCardSchema` | `schema/live-cards.schema.json` | Cards, source_defs, elements, compute, data bindings |
 
 All validators are synchronous, pure functions. They return `{ ok: boolean, errors?: ErrorObject[] }`.
 

package/board-livecards-server-runtime.js

@@ -38,6 +38,22 @@ function parseUrl(urlString) {
   return new URL(urlString, 'http://localhost');
 }
 
+/**
+ * Merges `extraFields` into the `extra` object inside a `.task-executor` JSON file.
+ * No-op if the file doesn't exist or isn't valid JSON.
+ */
+function refreshTaskExecutorExtra(runtimeDir, extraFields) {
+  const taskExecutorFile = path.join(runtimeDir, '.task-executor');
+  if (!fs.existsSync(taskExecutorFile)) return;
+  try {
+    const current = JSON.parse(fs.readFileSync(taskExecutorFile, 'utf-8'));
+    const merged = { ...current, extra: { ...(current.extra || {}), ...extraFields } };
+    fs.writeFileSync(taskExecutorFile, JSON.stringify(merged, null, 2), 'utf-8');
+  } catch {
+    // Silently ignore — board will still function, extra is best-effort
+  }
+}
+
 export function createRuntimeRequestDispatcher(runtime) {
   if (!runtime || typeof runtime !== 'object') {
     throw new Error('runtime is required');
@@ -147,6 +163,18 @@ export function createMultiBoardServerRuntime(options = {}) {
     const defaultInferenceAdapterPath = typeof entry.inferenceAdapterPath === 'string'
       ? entry.inferenceAdapterPath
       : options.defaultInferenceAdapterPath;
+    const gandalfCardsDir = typeof entry.gandalfCardsDir === 'string'
+      ? entry.gandalfCardsDir
+      : (options.defaultGandalfCardsDir || null);
+    const gandalfTaskExecutorPath = typeof entry.gandalfTaskExecutorPath === 'string'
+      ? entry.gandalfTaskExecutorPath
+      : (options.defaultGandalfTaskExecutorPath || null);
+    const gandalfChatHandlerPath = typeof entry.gandalfChatHandlerPath === 'string'
+      ? entry.gandalfChatHandlerPath
+      : (options.defaultGandalfChatHandlerPath || null);
+    const gandalfInferenceAdapterPath = typeof entry.gandalfInferenceAdapterPath === 'string'
+      ? entry.gandalfInferenceAdapterPath
+      : (options.defaultGandalfInferenceAdapterPath || null);
 
     const service = createExampleBoardServerRuntime({
       apiBasePath: `${apiBasePath}/${boardId}`,
@@ -160,7 +188,14 @@ export function createMultiBoardServerRuntime(options = {}) {
       defaultStepMachineCliPath,
       defaultChatHandlerPath,
       defaultInferenceAdapterPath,
+      gandalfCardsDir,
+      gandalfRuntimeDir: path.join(boardRoot, 'gandalf-runtime'),
+      gandalfRuntimeOutDir: path.join(boardRoot, 'gandalf-runtime-out'),
+      gandalfTaskExecutorPath,
+      gandalfChatHandlerPath,
+      gandalfInferenceAdapterPath,
       boardLiveCardsCliJs: options.boardLiveCardsCliJs,
+      serverUrl: options.serverUrl || null,
     });
 
     boardServiceCache.set(boardId, service);
@@ -346,6 +381,49 @@ export function createExampleBoardServerRuntime(options = {}) {
   const boardFile = path.join(boardDir, 'board-graph.json');
   const inventoryFile = path.join(boardDir, 'cards-inventory.jsonl');
 
+  // Board-cards: parallel runtime dirs for the board-manager board.
+  const gandalfCardsDir = options.gandalfCardsDir ? path.resolve(options.gandalfCardsDir) : null;
+  const gandalfRuntimeDir = path.resolve(options.gandalfRuntimeDir || path.join(path.dirname(boardDir), 'gandalf-runtime'));
+  const gandalfRuntimeOutDir = path.resolve(options.gandalfRuntimeOutDir || path.join(path.dirname(boardDir), 'gandalf-runtime-out'));
+  const tmpGandalfCardsDir = path.join(tmpSurfaceDir, 'tmp-gandalf-cards');
+  const gandalfInventoryFile = path.join(gandalfRuntimeDir, 'cards-inventory.jsonl');
+  const gandalfBoardFile = path.join(gandalfRuntimeDir, 'board-graph.json');
+  const gandalfStatusSnapshotFile = path.join(gandalfRuntimeOutDir, 'board-livegraph-status.json');
+
+  // Explicit gandalf-card executor paths — no fallback to regular-card paths.
+  const configuredGandalfTaskExecutorPath = typeof options.gandalfTaskExecutorPath === 'string' && options.gandalfTaskExecutorPath.trim()
+    ? (path.isAbsolute(options.gandalfTaskExecutorPath) ? options.gandalfTaskExecutorPath : path.resolve(process.cwd(), options.gandalfTaskExecutorPath))
+    : null;
+  const configuredGandalfChatHandlerPath = typeof options.gandalfChatHandlerPath === 'string' && options.gandalfChatHandlerPath.trim()
+    ? (path.isAbsolute(options.gandalfChatHandlerPath) ? options.gandalfChatHandlerPath : path.resolve(process.cwd(), options.gandalfChatHandlerPath))
+    : null;
+  const configuredGandalfInferenceAdapterPath = typeof options.gandalfInferenceAdapterPath === 'string' && options.gandalfInferenceAdapterPath.trim()
+    ? (path.isAbsolute(options.gandalfInferenceAdapterPath) ? options.gandalfInferenceAdapterPath : path.resolve(process.cwd(), options.gandalfInferenceAdapterPath))
+    : null;
+
+  // Server URL passed down from the hosting server (e.g. demo-server) so executors/handlers
+  // can call back to server-side proxy endpoints (e.g. /api/workiq/ask).
+  const serverUrl = typeof options.serverUrl === 'string' && options.serverUrl.trim()
+    ? options.serverUrl.trim().replace(/\/$/, '')
+    : null;
+
+  // Board-card ID cache: O(1) lookup, mtime-refreshed each SSE tick.
+  let _gandalfCardIds = new Set();
+  let _gandalfInventoryMtime = 0;
+  function _refreshGandalfCardCache() {
+    if (!fs.existsSync(gandalfInventoryFile)) { _gandalfCardIds = new Set(); return; }
+    const mtime = fs.statSync(gandalfInventoryFile).mtimeMs;
+    if (mtime === _gandalfInventoryMtime) return;
+    _gandalfInventoryMtime = mtime;
+    _gandalfCardIds = new Set(
+      fs.readFileSync(gandalfInventoryFile, 'utf-8')
+        .split('\n').filter(Boolean)
+        .map(l => { try { return JSON.parse(l).cardId; } catch { return null; } })
+        .filter(Boolean)
+    );
+  }
+  function isGandalfCard(cardId) { return _gandalfCardIds.has(cardId); }
+
   let didDemoSetup = false;
 
   function resolveCliJsPath() {
@@ -380,7 +458,8 @@ export function createExampleBoardServerRuntime(options = {}) {
 
   function ensureCardStorageDirs(cardId) {
     const safeCardId = String(cardId || '').replace(/[^a-zA-Z0-9_-]/g, '_') || 'unknown-card';
-    const cardDir = path.join(tmpCardsDir, safeCardId);
+    const baseDir = isGandalfCard(cardId) ? tmpGandalfCardsDir : tmpCardsDir;
+    const cardDir = path.join(baseDir, safeCardId);
     const filesDir = path.join(cardDir, 'files');
     const chatsDir = path.join(cardDir, 'chats');
     fs.mkdirSync(filesDir, { recursive: true });
@@ -491,41 +570,60 @@ export function createExampleBoardServerRuntime(options = {}) {
       .map((l) => JSON.parse(l));
   }
 
+  function readGandalfInventory() {
+    if (!fs.existsSync(gandalfInventoryFile)) return [];
+    return fs
+      .readFileSync(gandalfInventoryFile, 'utf-8')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .map((l) => JSON.parse(l));
+  }
+
   function readStatusSnapshot() {
-    if (!fs.existsSync(statusSnapshotFile)) return null;
-    return readJson(statusSnapshotFile);
+    const base = fs.existsSync(statusSnapshotFile) ? readJson(statusSnapshotFile) : null;
+    const boardSnap = fs.existsSync(gandalfStatusSnapshotFile) ? readJson(gandalfStatusSnapshotFile) : null;
+    if (!base && !boardSnap) return null;
+    if (!boardSnap) return base;
+    if (!base) return boardSnap;
+    return { ...base, tasks: { ...(base.tasks || {}), ...(boardSnap.tasks || {}) } };
   }
 
   function readCardDefinitions() {
-    const inv = readInventory();
-    const out = [];
-    for (const entry of inv) {
-      if (!entry || !entry.cardId || !entry.cardFilePath) continue;
-      if (!fs.existsSync(entry.cardFilePath)) continue;
-      out.push(readJson(entry.cardFilePath));
+    function readFromInventory(invFile) {
+      if (!fs.existsSync(invFile)) return [];
+      const inv = fs.readFileSync(invFile, 'utf-8').split('\n').map(l => l.trim()).filter(Boolean).map(l => JSON.parse(l));
+      const out = [];
+      for (const entry of inv) {
+        if (!entry || !entry.cardId || !entry.cardFilePath) continue;
+        if (!fs.existsSync(entry.cardFilePath)) continue;
+        out.push(readJson(entry.cardFilePath));
+      }
+      return out;
     }
-    return out;
+    return [...readFromInventory(inventoryFile), ...readFromInventory(gandalfInventoryFile)];
   }
 
   function readCardRuntimeArtifacts() {
-    const cardsOutDir = path.join(runtimeOutDir, 'cards');
-    if (!fs.existsSync(cardsOutDir)) return {};
-
-    const out = {};
-    for (const entry of fs.readdirSync(cardsOutDir, { withFileTypes: true })) {
-      if (!entry.isFile()) continue;
-      if (!entry.name.endsWith('.computed.json')) continue;
-      const cardId = entry.name.slice(0, -'.computed.json'.length);
-      out[cardId] = readJson(path.join(cardsOutDir, entry.name));
+    function readFromDir(dir) {
+      const cardsOutDir = path.join(dir, 'cards');
+      if (!fs.existsSync(cardsOutDir)) return {};
+      const out = {};
+      for (const entry of fs.readdirSync(cardsOutDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.computed.json')) continue;
+        const cardId = entry.name.slice(0, -'.computed.json'.length);
+        out[cardId] = readJson(path.join(cardsOutDir, entry.name));
+      }
+      return out;
     }
-    return out;
+    return { ...readFromDir(runtimeOutDir), ...readFromDir(gandalfRuntimeOutDir) };
   }
 
   function readSourcePayloads(cardDefinition) {
     const out = {};
-    if (!cardDefinition || !Array.isArray(cardDefinition.sources)) return out;
+    if (!cardDefinition || !Array.isArray(cardDefinition.source_defs)) return out;
 
-    for (const sourceDef of cardDefinition.sources) {
+    for (const sourceDef of cardDefinition.source_defs) {
       if (!sourceDef || !sourceDef.bindTo || !sourceDef.outputFile) continue;
       const filePath = path.join(boardDir, cardDefinition.id, sourceDef.outputFile);
       if (!fs.existsSync(filePath)) continue;
@@ -561,7 +659,8 @@ export function createExampleBoardServerRuntime(options = {}) {
   }
 
   function readChatSignal(cardId) {
-    const chatsDir = path.join(tmpCardsDir, cardId, 'chats');
+    const baseDir = isGandalfCard(cardId) ? tmpGandalfCardsDir : tmpCardsDir;
+    const chatsDir = path.join(baseDir, cardId, 'chats');
     if (!fs.existsSync(chatsDir)) {
       return { count: 0, latest_mtime_ms: 0, processing: false };
     }
@@ -644,6 +743,16 @@ export function createExampleBoardServerRuntime(options = {}) {
       fs.copyFileSync(src, dst);
     }
 
+    // Copy gandalf-card templates if gandalfCardsDir is configured.
+    if (gandalfCardsDir && fs.existsSync(gandalfCardsDir)) {
+      fs.rmSync(tmpGandalfCardsDir, { recursive: true, force: true });
+      fs.mkdirSync(tmpGandalfCardsDir, { recursive: true });
+      for (const entry of fs.readdirSync(gandalfCardsDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.json')) continue;
+        fs.copyFileSync(path.join(gandalfCardsDir, entry.name), path.join(tmpGandalfCardsDir, entry.name));
+      }
+    }
+
     // Concatenate agent-instructions*.md files into copilot-instructions.md at boardSetupRoot
     const boardSetupRoot = path.dirname(boardDir);
     const agentInstructionFiles = ['agent-instructions.md', 'agent-instructions-cardlayout.md'];
@@ -662,8 +771,12 @@ export function createExampleBoardServerRuntime(options = {}) {
     didDemoSetup = true;
   }
 
+  function isDemoSetupDone() {
+    return didDemoSetup && fs.existsSync(tmpCardsDir);
+  }
+
   function ensureDemoSetup() {
-    if (didDemoSetup && fs.existsSync(tmpCardsDir)) return;
+    if (isDemoSetupDone()) return;
     demoPrepSetup();
   }
 
@@ -713,6 +826,69 @@ export function createExampleBoardServerRuntime(options = {}) {
     return resolved;
   }
 
+  function resolveGandalfTaskExecutorPath() {
+    if (!configuredGandalfTaskExecutorPath) return null;
+    if (!fs.existsSync(configuredGandalfTaskExecutorPath)) {
+      const err = new Error(`Gandalf task executor script not found: ${configuredGandalfTaskExecutorPath}`);
+      err.statusCode = 400;
+      throw err;
+    }
+    return configuredGandalfTaskExecutorPath;
+  }
+
+  function resolveGandalfChatHandlerPath() {
+    if (!configuredGandalfChatHandlerPath) return null;
+    if (!fs.existsSync(configuredGandalfChatHandlerPath)) {
+      const err = new Error(`Gandalf chat handler script not found: ${configuredGandalfChatHandlerPath}`);
+      err.statusCode = 400;
+      throw err;
+    }
+    return configuredGandalfChatHandlerPath;
+  }
+
+  function resolveGandalfInferenceAdapterPath() {
+    if (!configuredGandalfInferenceAdapterPath) return null;
+    if (!fs.existsSync(configuredGandalfInferenceAdapterPath)) {
+      const err = new Error(`Gandalf inference adapter script not found: ${configuredGandalfInferenceAdapterPath}`);
+      err.statusCode = 400;
+      throw err;
+    }
+    return configuredGandalfInferenceAdapterPath;
+  }
+
+  function initGandalfCards() {
+    const taskExecutorPath = resolveGandalfTaskExecutorPath();
+    if (!taskExecutorPath) return; // gandalf-cards not configured; skip.
+    fs.mkdirSync(gandalfRuntimeDir, { recursive: true });
+    const chatHandlerPath = resolveGandalfChatHandlerPath();
+    const inferenceAdapterPath = resolveGandalfInferenceAdapterPath();
+    const taskExecutorCmd = `${shellQuote(process.execPath)} ${shellQuote(taskExecutorPath)}`;
+    const chatHandlerCmd = chatHandlerPath ? `${shellQuote(process.execPath)} ${shellQuote(chatHandlerPath)}` : null;
+    const inferenceAdapterCmd = inferenceAdapterPath ? `${shellQuote(process.execPath)} ${shellQuote(inferenceAdapterPath)}` : null;
+    const boardSetupRoot = path.dirname(boardDir);
+    const taskExecutorExtra = JSON.stringify({
+      boardSetupRoot,
+      boardId,
+      boardRuntimeDir:  path.relative(boardSetupRoot, gandalfRuntimeDir),
+      runtimeStatusDir: path.relative(boardSetupRoot, gandalfRuntimeOutDir),
+      cardsDir:         path.relative(boardSetupRoot, tmpGandalfCardsDir),
+      ...(serverUrl ? { serverUrl } : {}),
+    });
+    const initArgs = ['init', gandalfRuntimeDir, '--task-executor', taskExecutorCmd, '--task-executor-extra', taskExecutorExtra];
+    if (chatHandlerCmd) initArgs.push('--chat-handler', chatHandlerCmd);
+    if (inferenceAdapterCmd) initArgs.push('--inference-adapter', inferenceAdapterCmd);
+    initArgs.push('--runtime-out', gandalfRuntimeOutDir);
+    try {
+      runCli(initArgs);
+    } catch (err) {
+      const msg = String((err && err.message) || err);
+      if (!msg.includes('no valid board-graph.json')) throw err;
+      clearDirContents(gandalfRuntimeDir);
+      fs.mkdirSync(gandalfRuntimeDir, { recursive: true });
+      runCli(initArgs);
+    }
+  }
+
   function initBoard(taskExecutorPathParam, chatHandlerPathParam, inferenceAdapterPathParam) {
     fs.mkdirSync(boardDir, { recursive: true });
 
@@ -727,7 +903,17 @@ export function createExampleBoardServerRuntime(options = {}) {
       ? `${shellQuote(process.execPath)} ${shellQuote(inferenceAdapterPath)}`
       : null;
 
-    const initArgs = ['init', boardDir, '--task-executor', taskExecutorCmd];
+    const boardSetupRoot = path.dirname(boardDir);
+    const taskExecutorExtra = JSON.stringify({
+      boardSetupRoot,
+      boardId,
+      boardRuntimeDir:  path.relative(boardSetupRoot, boardDir),
+      runtimeStatusDir: path.relative(boardSetupRoot, runtimeOutDir),
+      cardsDir:         path.relative(boardSetupRoot, tmpCardsDir),
+      ...(serverUrl ? { serverUrl } : {}),
+    });
+
+    const initArgs = ['init', boardDir, '--task-executor', taskExecutorCmd, '--task-executor-extra', taskExecutorExtra];
     if (chatHandlerCmd) initArgs.push('--chat-handler', chatHandlerCmd);
     if (inferenceAdapterCmd) initArgs.push('--inference-adapter', inferenceAdapterCmd);
     initArgs.push('--runtime-out', runtimeOutDir);
@@ -762,6 +948,31 @@ export function createExampleBoardServerRuntime(options = {}) {
       clearDirContents(boardDir);
       initBoard(taskExecutorPathParam, chatHandlerPathParam, inferenceAdapterPathParam);
     }
+
+    // Always refresh the extra in .task-executor so serverUrl and other runtime fields stay current
+    // even when initBoard is skipped (board already initialized from a previous run).
+    refreshTaskExecutorExtra(boardDir, {
+      boardSetupRoot: path.dirname(boardDir),
+      boardId,
+      boardRuntimeDir:  path.relative(path.dirname(boardDir), boardDir),
+      runtimeStatusDir: path.relative(path.dirname(boardDir), runtimeOutDir),
+      cardsDir:         path.relative(path.dirname(boardDir), tmpCardsDir),
+      ...(serverUrl ? { serverUrl } : {}),
+    });
+
+    // Board-cards runtime: init if configured but not yet initialized.
+    if (resolveGandalfTaskExecutorPath() && !fs.existsSync(gandalfBoardFile)) {
+      initGandalfCards();
+    }
+  }
+
+  function bootstrapGandalfCards() {
+    if (!fs.existsSync(tmpGandalfCardsDir)) return;
+    if (!fs.existsSync(gandalfBoardFile)) return; // runtime not initialized; initBoardAndSetup handles it
+    const jsonFiles = (fs.readdirSync(tmpGandalfCardsDir)).filter(f => f.endsWith('.json'));
+    if (!jsonFiles.length) return;
+    runCli(['upsert-card', '--rg', gandalfRuntimeDir, '--card-glob', path.join(tmpGandalfCardsDir, '*.json')]);
+    _refreshGandalfCardCache();
   }
 
   function bootstrapCards() {
@@ -772,9 +983,14 @@ export function createExampleBoardServerRuntime(options = {}) {
   function bootstrapBoard() {
     initBoardAndSetup();
     bootstrapCards();
+    bootstrapGandalfCards();
   }
 
   function findCardPath(cardId) {
+    if (isGandalfCard(cardId)) {
+      const found = readGandalfInventory().find((e) => e.cardId === cardId);
+      return found ? found.cardFilePath : null;
+    }
     const inv = readInventory();
     const found = inv.find((e) => e.cardId === cardId);
     return found ? found.cardFilePath : null;
@@ -795,7 +1011,8 @@ export function createExampleBoardServerRuntime(options = {}) {
     fs.writeFileSync(cardPath, JSON.stringify(nextCard, null, 2));
 
     if (syncBoard) {
-      runCli(['upsert-card', '--rg', boardDir, '--card', cardPath, '--restart']);
+      const rg = isGandalfCard(cardId) ? gandalfRuntimeDir : boardDir;
+      runCli(['upsert-card', '--rg', rg, '--card', cardPath, '--restart']);
     }
   }
 
@@ -992,18 +1209,20 @@ export function createExampleBoardServerRuntime(options = {}) {
   }
 
   // Fire-and-forget invocation of .chat-handler after a user chat message is persisted.
-  // boardDir/.chat-handler must contain the handler command as a single-line string.
+  // The handler file lives in the appropriate runtime dir (.chat-handler).
   // Called with: --boardId <id> --cardId <id> --extraEncJson <base64json>
   // extraEncJson decodes to:
   //   boardSetupRoot  — absolute path to board root (parent of runtime/, surface/, runtime-out/)
-  //   boardRuntimeDir — relative: 'runtime'
+  //   boardRuntimeDir — relative: 'runtime' (or 'gandalf-runtime' for gandalf cards)
   //   runtimeStatusDir— relative: 'runtime-out'
-  //   cardsDir        — relative: 'surface/tmp-cards'
+  //   cardsDir        — relative: 'surface/tmp-cards' (or 'surface/tmp-gandalf-cards')
   //   chatDir         — relative (from cardsDir): e.g. 'card-portfolio/chats'
   //   lastChatFile    — filename of the just-written user message, e.g. '001_user.txt'
   // Handler failures are logged and silently ignored — chat-send response is never affected.
   function invokeChatHandler(cardId, chatsDir, lastChatFile) {
-    const handlerFile = path.join(boardDir, '.chat-handler');
+    const isGandalf = isGandalfCard(cardId);
+    const runtimeDir = isGandalf ? gandalfRuntimeDir : boardDir;
+    const handlerFile = path.join(runtimeDir, '.chat-handler');
     if (!fs.existsSync(handlerFile)) return;
     const handlerCmd = fs.readFileSync(handlerFile, 'utf-8').trim();
     if (!handlerCmd) return;
@@ -1012,11 +1231,12 @@ export function createExampleBoardServerRuntime(options = {}) {
     try { fs.mkdirSync(chatsDir, { recursive: true }); fs.writeFileSync(processingFile, '', 'utf-8'); } catch {}
     const extra = Buffer.from(JSON.stringify({
       boardSetupRoot,
-      boardRuntimeDir:  path.relative(boardSetupRoot, boardDir),
-      runtimeStatusDir: path.relative(boardSetupRoot, runtimeOutDir),
-      cardsDir:         path.relative(boardSetupRoot, tmpCardsDir),
+      boardRuntimeDir:  path.relative(boardSetupRoot, isGandalf ? gandalfRuntimeDir : boardDir),
+      runtimeStatusDir: path.relative(boardSetupRoot, isGandalf ? gandalfRuntimeOutDir : runtimeOutDir),
+      cardsDir:         path.relative(boardSetupRoot, isGandalf ? tmpGandalfCardsDir : tmpCardsDir),
       chatDir:          chatsDir,
       lastChatFile,
+      ...(serverUrl ? { serverUrl } : {}),
     })).toString('base64');
     try {
       const proc = spawn(handlerCmd, [
@@ -1180,6 +1400,10 @@ export function createExampleBoardServerRuntime(options = {}) {
     const poll = setInterval(() => {
       try {
         runCli(['process-accumulated-events', '--rg', boardDir]);
+        if (fs.existsSync(gandalfBoardFile)) {
+          runCli(['process-accumulated-events', '--rg', gandalfRuntimeDir]);
+        }
+        _refreshGandalfCardCache();
 
         const nextPayload = buildPublishedRuntimePayload();
         const nextHash = stablePayloadString(nextPayload);
@@ -1318,8 +1542,8 @@ export function createExampleBoardServerRuntime(options = {}) {
         const idx = parseInt(cardFileDownloadMatch[2], 10);
         const expectedStoredName = url.searchParams.get('sn');
 
-        const cardPath = path.join(tmpCardsDir, `${cardId}.json`);
-        if (!fs.existsSync(cardPath)) {
+        const cardPath = findCardPath(cardId);
+        if (!cardPath || !fs.existsSync(cardPath)) {
           json(res, 404, { error: 'Card not found' });
           return true;
         }
@@ -1395,6 +1619,7 @@ export function createExampleBoardServerRuntime(options = {}) {
     runCli,
     demoPrepSetup,
     ensureDemoSetup,
+    isDemoSetupDone,
     buildPublishedRuntimePayload,
     handleRuntimeApi,
     clearChatRecords,