yaml-flow 3.1.1 → 5.0.0

package/dist/cli/board-live-cards-cli.js

@@ -0,0 +1,2702 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { execFileSync, spawn, execFile } from 'child_process';
+import { fileURLToPath } from 'url';
+import fg from 'fast-glob';
+import { lockSync } from 'proper-lockfile';
+import jsonata2 from 'jsonata';
+import 'ajv-formats';
+
+// src/cli/board-live-cards-cli.ts
+
+// src/event-graph/constants.ts
+var TASK_STATUS = {
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  INACTIVATED: "inactivated"
+};
+
+// src/event-graph/graph-helpers.ts
+function getProvides(task) {
+  if (!task) return [];
+  if (Array.isArray(task.provides)) return task.provides;
+  return [];
+}
+function getRequires(task) {
+  if (!task) return [];
+  if (Array.isArray(task.requires)) return task.requires;
+  return [];
+}
+function getAllTasks(graph) {
+  return graph.tasks ?? {};
+}
+function isNonActiveTask(taskState) {
+  if (!taskState) return false;
+  return taskState.status === TASK_STATUS.FAILED || taskState.status === TASK_STATUS.INACTIVATED;
+}
+function getRefreshStrategy(taskConfig, graphSettings) {
+  return taskConfig.refreshStrategy ?? graphSettings?.refreshStrategy ?? "data-changed";
+}
+function getMaxExecutions(taskConfig) {
+  return taskConfig.maxExecutions;
+}
+function computeAvailableOutputs(graph, taskStates) {
+  const outputs = /* @__PURE__ */ new Set();
+  for (const [taskName, taskState] of Object.entries(taskStates)) {
+    if (taskState.status === TASK_STATUS.COMPLETED) {
+      const taskConfig = graph.tasks[taskName];
+      if (taskConfig) {
+        const provides = getProvides(taskConfig);
+        provides.forEach((output) => outputs.add(output));
+      }
+    }
+  }
+  return Array.from(outputs);
+}
+function groupTasksByProvides(candidateTaskNames, tasks) {
+  const outputGroups = {};
+  candidateTaskNames.forEach((taskName) => {
+    const task = tasks[taskName];
+    if (!task) return;
+    const provides = getProvides(task);
+    provides.forEach((output) => {
+      if (!outputGroups[output]) {
+        outputGroups[output] = [];
+      }
+      outputGroups[output].push(taskName);
+    });
+  });
+  return outputGroups;
+}
+
+// src/event-graph/task-transitions.ts
+function applyTaskStart(state, taskName) {
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
+  const updatedTask = {
+    ...existingTask,
+    status: "running",
+    startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+    progress: 0,
+    error: void 0
+  };
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function applyTaskCompletion(state, graph, taskName, result, dataHash, data) {
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
+  const taskConfig = graph.tasks[taskName];
+  if (!taskConfig) {
+    throw new Error(`Task "${taskName}" not found in graph`);
+  }
+  let outputTokens;
+  if (result && taskConfig.on && taskConfig.on[result]) {
+    outputTokens = taskConfig.on[result];
+  } else {
+    outputTokens = getProvides(taskConfig);
+  }
+  const lastConsumedHashes = { ...existingTask.lastConsumedHashes };
+  const requires = taskConfig.requires ?? [];
+  for (const token of requires) {
+    for (const [otherName, otherConfig] of Object.entries(graph.tasks)) {
+      if (getProvides(otherConfig).includes(token)) {
+        const otherState = state.tasks[otherName];
+        if (otherState?.lastDataHash) {
+          lastConsumedHashes[token] = otherState.lastDataHash;
+        }
+        break;
+      }
+    }
+  }
+  const updatedTask = {
+    ...existingTask,
+    status: "completed",
+    completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+    executionCount: existingTask.executionCount + 1,
+    lastEpoch: existingTask.executionCount + 1,
+    lastDataHash: dataHash,
+    data,
+    lastConsumedHashes,
+    error: void 0
+  };
+  const newOutputs = [.../* @__PURE__ */ new Set([...state.availableOutputs, ...outputTokens])];
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    availableOutputs: newOutputs,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function applyTaskFailure(state, graph, taskName, error) {
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
+  const taskConfig = graph.tasks[taskName];
+  if (taskConfig?.retry) {
+    const retryCount = existingTask.retryCount + 1;
+    if (retryCount <= taskConfig.retry.max_attempts) {
+      const updatedTask2 = {
+        ...existingTask,
+        status: "not-started",
+        retryCount,
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+        error
+      };
+      return {
+        ...state,
+        tasks: { ...state.tasks, [taskName]: updatedTask2 },
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    }
+  }
+  const updatedTask = {
+    ...existingTask,
+    status: "failed",
+    failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+    error,
+    executionCount: existingTask.executionCount + 1
+  };
+  let newOutputs = state.availableOutputs;
+  if (taskConfig?.on_failure && taskConfig.on_failure.length > 0) {
+    newOutputs = [.../* @__PURE__ */ new Set([...state.availableOutputs, ...taskConfig.on_failure])];
+  }
+  if (taskConfig?.circuit_breaker && updatedTask.executionCount >= taskConfig.circuit_breaker.max_executions) {
+    const breakTokens = taskConfig.circuit_breaker.on_break;
+    newOutputs = [.../* @__PURE__ */ new Set([...newOutputs, ...breakTokens])];
+  }
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    availableOutputs: newOutputs,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function applyTaskProgress(state, taskName, message, progress) {
+  const existingTask = state.tasks[taskName] ?? createDefaultGraphEngineStore();
+  const updatedTask = {
+    ...existingTask,
+    progress: typeof progress === "number" ? progress : existingTask.progress,
+    messages: [
+      ...existingTask.messages ?? [],
+      ...message ? [{ message, timestamp: (/* @__PURE__ */ new Date()).toISOString(), status: existingTask.status }] : []
+    ],
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function applyTaskRestart(state, taskName) {
+  const existingTask = state.tasks[taskName];
+  if (!existingTask) return state;
+  const updatedTask = {
+    ...existingTask,
+    status: "not-started",
+    startedAt: void 0,
+    completedAt: void 0,
+    failedAt: void 0,
+    error: void 0,
+    data: void 0,
+    progress: null,
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    ...state,
+    tasks: { ...state.tasks, [taskName]: updatedTask },
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function createDefaultGraphEngineStore() {
+  return {
+    status: "not-started",
+    executionCount: 0,
+    retryCount: 0,
+    lastEpoch: 0,
+    messages: [],
+    progress: null
+  };
+}
+
+// src/continuous-event-graph/core.ts
+function createLiveGraph(config, executionId) {
+  const id = `live-${Date.now()}`;
+  const tasks = {};
+  for (const taskName of Object.keys(config.tasks)) {
+    tasks[taskName] = createDefaultGraphEngineStore2();
+  }
+  const state = {
+    status: "running",
+    tasks,
+    availableOutputs: [],
+    stuckDetection: { is_stuck: false, stuck_description: null, outputs_unresolvable: [], tasks_blocked: [] },
+    lastUpdated: (/* @__PURE__ */ new Date()).toISOString(),
+    executionId: id,
+    executionConfig: {
+      executionMode: config.settings.execution_mode ?? "eligibility-mode",
+      conflictStrategy: config.settings.conflict_strategy ?? "alphabetical",
+      completionStrategy: config.settings.completion
+    }
+  };
+  return { config, state };
+}
+function applyEvent(live, event) {
+  const { config, state } = live;
+  if ("executionId" in event && event.executionId && event.executionId !== state.executionId) {
+    return live;
+  }
+  switch (event.type) {
+    // --- Execution state transitions ---
+    case "task-started":
+      return { config, state: applyTaskStart(state, event.taskName) };
+    case "task-completed":
+      return { config, state: applyTaskCompletion(state, config, event.taskName, event.result, event.dataHash, event.data) };
+    case "task-failed":
+      return { config, state: applyTaskFailure(state, config, event.taskName, event.error) };
+    case "task-progress":
+      return { config, state: applyTaskProgress(state, event.taskName, event.message, event.progress) };
+    case "task-restart":
+      return { config, state: applyTaskRestart(state, event.taskName) };
+    case "inject-tokens":
+      return {
+        config,
+        state: {
+          ...state,
+          availableOutputs: [.../* @__PURE__ */ new Set([...state.availableOutputs, ...event.tokens])],
+          lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+        }
+      };
+    case "agent-action":
+      return { config, state: applyAgentAction(state, event.action) };
+    // --- Structural mutations ---
+    case "task-upsert":
+      return addNode(live, event.taskName, event.taskConfig);
+    case "task-removal":
+      return removeNode(live, event.taskName);
+    case "node-requires-add":
+      return addRequires(live, event.nodeName, event.tokens);
+    case "node-requires-remove":
+      return removeRequires(live, event.nodeName, event.tokens);
+    case "node-provides-add":
+      return addProvides(live, event.nodeName, event.tokens);
+    case "node-provides-remove":
+      return removeProvides(live, event.nodeName, event.tokens);
+    default:
+      return live;
+  }
+}
+function applyEvents(live, events) {
+  return events.reduce((current, event) => applyEvent(current, event), live);
+}
+function addNode(live, name, taskConfig) {
+  const exists = !!live.config.tasks[name];
+  return {
+    config: {
+      ...live.config,
+      tasks: { ...live.config.tasks, [name]: taskConfig }
+    },
+    state: {
+      ...live.state,
+      tasks: {
+        ...live.state.tasks,
+        [name]: exists ? live.state.tasks[name] : createDefaultGraphEngineStore2()
+      },
+      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function removeNode(live, name) {
+  if (!live.config.tasks[name]) return live;
+  const { [name]: _removedConfig, ...remainingTasks } = live.config.tasks;
+  const { [name]: _removedState, ...remainingStates } = live.state.tasks;
+  return {
+    config: {
+      ...live.config,
+      tasks: remainingTasks
+    },
+    state: {
+      ...live.state,
+      tasks: remainingStates,
+      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+    }
+  };
+}
+function addRequires(live, nodeName, tokens) {
+  const task = live.config.tasks[nodeName];
+  if (!task) return live;
+  const current = getRequires(task);
+  const toAdd = tokens.filter((t) => !current.includes(t));
+  if (toAdd.length === 0) return live;
+  return {
+    config: {
+      ...live.config,
+      tasks: {
+        ...live.config.tasks,
+        [nodeName]: { ...task, requires: [...current, ...toAdd] }
+      }
+    },
+    state: live.state
+  };
+}
+function removeRequires(live, nodeName, tokens) {
+  const task = live.config.tasks[nodeName];
+  if (!task) return live;
+  const current = getRequires(task);
+  const remaining = current.filter((t) => !tokens.includes(t));
+  if (remaining.length === current.length) return live;
+  return {
+    config: {
+      ...live.config,
+      tasks: {
+        ...live.config.tasks,
+        [nodeName]: { ...task, requires: remaining }
+      }
+    },
+    state: live.state
+  };
+}
+function addProvides(live, nodeName, tokens) {
+  const task = live.config.tasks[nodeName];
+  if (!task) return live;
+  const current = getProvides(task);
+  const toAdd = tokens.filter((t) => !current.includes(t));
+  if (toAdd.length === 0) return live;
+  return {
+    config: {
+      ...live.config,
+      tasks: {
+        ...live.config.tasks,
+        [nodeName]: { ...task, provides: [...current, ...toAdd] }
+      }
+    },
+    state: live.state
+  };
+}
+function removeProvides(live, nodeName, tokens) {
+  const task = live.config.tasks[nodeName];
+  if (!task) return live;
+  const current = getProvides(task);
+  const remaining = current.filter((t) => !tokens.includes(t));
+  if (remaining.length === current.length) return live;
+  return {
+    config: {
+      ...live.config,
+      tasks: {
+        ...live.config.tasks,
+        [nodeName]: { ...task, provides: remaining }
+      }
+    },
+    state: live.state
+  };
+}
+function snapshot(live) {
+  return {
+    version: 1,
+    config: live.config,
+    state: live.state,
+    snapshotAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function restore(data) {
+  if (!data || typeof data !== "object") {
+    throw new Error("Invalid snapshot: expected an object");
+  }
+  const snap = data;
+  if (!snap.config || typeof snap.config !== "object") {
+    throw new Error('Invalid snapshot: missing or invalid "config"');
+  }
+  if (!snap.state || typeof snap.state !== "object") {
+    throw new Error('Invalid snapshot: missing or invalid "state"');
+  }
+  const config = snap.config;
+  const state = snap.state;
+  if (!config.settings || typeof config.settings !== "object") {
+    throw new Error("Invalid snapshot: config.settings missing");
+  }
+  if (!config.tasks || typeof config.tasks !== "object") {
+    throw new Error("Invalid snapshot: config.tasks missing");
+  }
+  if (!state.tasks || typeof state.tasks !== "object") {
+    throw new Error("Invalid snapshot: state.tasks missing");
+  }
+  if (!Array.isArray(state.availableOutputs)) {
+    throw new Error("Invalid snapshot: state.availableOutputs must be an array");
+  }
+  return { config, state };
+}
+function createDefaultGraphEngineStore2() {
+  return {
+    status: "not-started",
+    executionCount: 0,
+    retryCount: 0,
+    lastEpoch: 0,
+    messages: [],
+    progress: null
+  };
+}
+function applyAgentAction(state, action) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  switch (action) {
+    case "stop":
+      return { ...state, status: "stopped", lastUpdated: now };
+    case "pause":
+      return { ...state, status: "paused", lastUpdated: now };
+    case "resume":
+      return { ...state, status: "running", lastUpdated: now };
+    default:
+      return state;
+  }
+}
+
+// src/continuous-event-graph/schedule.ts
+function schedule(live) {
+  const { config, state } = live;
+  const graphTasks = getAllTasks(config);
+  const taskNames = Object.keys(graphTasks);
+  if (taskNames.length === 0) {
+    return { eligible: [], pending: [], unresolved: [], blocked: [], conflicts: {} };
+  }
+  const producerMap = buildProducerMap(graphTasks);
+  const computedOutputs = computeAvailableOutputs(config, state.tasks);
+  const availableOutputs = /* @__PURE__ */ new Set([...computedOutputs, ...state.availableOutputs]);
+  const eligible = [];
+  const pending = [];
+  const unresolved = [];
+  const blocked = [];
+  for (const [taskName, taskConfig] of Object.entries(graphTasks)) {
+    const taskState = state.tasks[taskName];
+    const strategy = getRefreshStrategy(taskConfig, config.settings);
+    const rerunnable = strategy !== "once";
+    if (taskState?.status === TASK_STATUS.RUNNING || isNonActiveTask(taskState)) {
+      continue;
+    }
+    const maxExec = getMaxExecutions(taskConfig);
+    if (maxExec !== void 0 && taskState && taskState.executionCount >= maxExec) {
+      continue;
+    }
+    if (taskConfig.circuit_breaker && taskState && taskState.executionCount >= taskConfig.circuit_breaker.max_executions) {
+      continue;
+    }
+    if (!rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      continue;
+    }
+    if (rerunnable && taskState?.status === TASK_STATUS.COMPLETED) {
+      const requires2 = getRequires(taskConfig);
+      let shouldSkip = false;
+      switch (strategy) {
+        case "data-changed": {
+          if (requires2.length > 0) {
+            const hasChangedData = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (!otherState) continue;
+                  const consumed = taskState.lastConsumedHashes?.[req];
+                  if (otherState.lastDataHash == null) {
+                    return otherState.executionCount > taskState.lastEpoch;
+                  }
+                  return otherState.lastDataHash !== consumed;
+                }
+              }
+              return false;
+            });
+            if (!hasChangedData) shouldSkip = true;
+          } else {
+            shouldSkip = true;
+          }
+          break;
+        }
+        case "epoch-changed": {
+          if (requires2.length > 0) {
+            const hasRefreshed = requires2.some((req) => {
+              for (const [otherName, otherConfig] of Object.entries(graphTasks)) {
+                if (getProvides(otherConfig).includes(req)) {
+                  const otherState = state.tasks[otherName];
+                  if (otherState && otherState.executionCount > taskState.lastEpoch) return true;
+                }
+              }
+              return false;
+            });
+            if (!hasRefreshed) shouldSkip = true;
+          } else {
+            shouldSkip = true;
+          }
+          break;
+        }
+        case "time-based": {
+          const interval = taskConfig.refreshInterval ?? 0;
+          if (interval <= 0) {
+            shouldSkip = true;
+            break;
+          }
+          const completedAt = taskState.completedAt;
+          if (!completedAt) {
+            shouldSkip = true;
+            break;
+          }
+          const elapsedSec = (Date.now() - Date.parse(completedAt)) / 1e3;
+          if (elapsedSec < interval) shouldSkip = true;
+          break;
+        }
+        case "manual":
+          shouldSkip = true;
+          break;
+      }
+      if (shouldSkip) continue;
+    }
+    const requires = getRequires(taskConfig);
+    if (requires.length === 0) {
+      eligible.push(taskName);
+      continue;
+    }
+    const missingTokens = [];
+    const pendingTokens = [];
+    const failedTokenInfo = [];
+    for (const token of requires) {
+      if (availableOutputs.has(token)) continue;
+      const producers = producerMap[token] || [];
+      if (producers.length === 0) {
+        missingTokens.push(token);
+      } else {
+        const allFailed = producers.every((p) => isNonActiveTask(state.tasks[p]));
+        if (allFailed) {
+          failedTokenInfo.push({ token, failedProducer: producers[0] });
+        } else {
+          pendingTokens.push(token);
+        }
+      }
+    }
+    if (missingTokens.length > 0) {
+      unresolved.push({ taskName, missingTokens });
+    } else if (failedTokenInfo.length > 0) {
+      blocked.push({
+        taskName,
+        failedTokens: failedTokenInfo.map((f) => f.token),
+        failedProducers: [...new Set(failedTokenInfo.map((f) => f.failedProducer))]
+      });
+    } else if (pendingTokens.length > 0) {
+      pending.push({ taskName, waitingOn: pendingTokens });
+    } else {
+      eligible.push(taskName);
+    }
+  }
+  const conflicts = {};
+  if (eligible.length > 1) {
+    const outputGroups = groupTasksByProvides(eligible, graphTasks);
+    for (const [outputKey, groupTasks] of Object.entries(outputGroups)) {
+      if (groupTasks.length > 1) {
+        conflicts[outputKey] = groupTasks;
+      }
+    }
+  }
+  return { eligible, pending, unresolved, blocked, conflicts };
+}
+function buildProducerMap(tasks) {
+  const map = {};
+  for (const [name, config] of Object.entries(tasks)) {
+    for (const token of getProvides(config)) {
+      if (!map[token]) map[token] = [];
+      map[token].push(name);
+    }
+    if (config.on) {
+      for (const tokens of Object.values(config.on)) {
+        for (const token of tokens) {
+          if (!map[token]) map[token] = [];
+          if (!map[token].includes(name)) map[token].push(name);
+        }
+      }
+    }
+    if (config.on_failure) {
+      for (const token of config.on_failure) {
+        if (!map[token]) map[token] = [];
+        if (!map[token].includes(name)) map[token].push(name);
+      }
+    }
+  }
+  return map;
+}
+
+// src/continuous-event-graph/journal.ts
+var MemoryJournal = class {
+  buffer = [];
+  append(event) {
+    this.buffer.push(event);
+  }
+  drain() {
+    const events = this.buffer;
+    this.buffer = [];
+    return events;
+  }
+  get size() {
+    return this.buffer.length;
+  }
+};
+
+// src/continuous-event-graph/reactive.ts
+function computeDataHash(data) {
+  const json = stableStringify(data);
+  return fnv1a64Hex(json);
+}
+function stableStringify(value) {
+  if (value === null || value === void 0 || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k])).join(",") + "}";
+}
+function fnv1a64Hex(input) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mod = 0xffffffffffffffffn;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = hash * prime & mod;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function base64UrlEncode(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "utf8").toString("base64url");
+  }
+  if (typeof btoa === "function") {
+    const bytes = new TextEncoder().encode(input);
+    let binary = "";
+    for (const b of bytes) binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+  }
+  throw new Error("No base64 encoder available in this runtime");
+}
+function base64UrlDecode(input) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(input, "base64url").toString("utf8");
+  }
+  if (typeof atob === "function") {
+    const base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  throw new Error("No base64 decoder available in this runtime");
+}
+function encodeCallbackToken(taskName) {
+  const payload = JSON.stringify({ t: taskName, n: Date.now().toString(36) + Math.random().toString(36).slice(2, 6) });
+  return base64UrlEncode(payload);
+}
+function decodeCallbackToken(token) {
+  try {
+    const payload = JSON.parse(base64UrlDecode(token));
+    if (typeof payload?.t === "string") return { taskName: payload.t };
+    return null;
+  } catch {
+    return null;
+  }
+}
+function createReactiveGraph(configOrLive, options, executionId) {
+  const {
+    handlers: initialHandlers,
+    onDrain
+  } = options;
+  const inputQueue = new MemoryJournal();
+  let live = "state" in configOrLive && "config" in configOrLive ? configOrLive : createLiveGraph(configOrLive);
+  let disposed = false;
+  const handlers = new Map(Object.entries(initialHandlers));
+  const internalJournal = new MemoryJournal();
+  let draining = false;
+  let drainQueued = false;
+  function drain() {
+    if (disposed) return;
+    if (draining) {
+      drainQueued = true;
+      return;
+    }
+    draining = true;
+    try {
+      do {
+        drainQueued = false;
+        drainOnce();
+      } while (drainQueued);
+    } finally {
+      draining = false;
+    }
+  }
+  function drainOnce() {
+    const internalEvents = internalJournal.drain();
+    const inputEvents = inputQueue.drain();
+    const events = [...internalEvents, ...inputEvents];
+    if (events.length > 0) {
+      live = applyEvents(live, events);
+    }
+    const result = schedule(live);
+    if (events.length > 0) {
+      onDrain?.(events, live, result);
+    }
+    for (const taskName of result.eligible) {
+      dispatchTask(taskName);
+    }
+    for (const event of events) {
+      if (event.type === "task-progress") {
+        const { taskName, update } = event;
+        const taskConfig = live.config.tasks[taskName];
+        if (!taskConfig) continue;
+        const taskState = live.state.tasks[taskName];
+        if (!taskState || taskState.status !== "running") continue;
+        const callbackToken = encodeCallbackToken(taskName);
+        runPipeline(taskName, callbackToken, update).catch((error) => {
+          if (disposed) return;
+          internalJournal.append({
+            type: "task-failed",
+            taskName,
+            error: error.message ?? String(error),
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          drain();
+        });
+      }
+    }
+  }
+  function resolveUpstreamState(taskName) {
+    const taskConfig = live.config.tasks[taskName];
+    const requires = taskConfig.requires ?? [];
+    const tokenToTask = /* @__PURE__ */ new Map();
+    for (const [name, cfg] of Object.entries(live.config.tasks)) {
+      for (const token of cfg.provides ?? []) {
+        tokenToTask.set(token, name);
+      }
+    }
+    const state = {};
+    for (const token of requires) {
+      const producerTask = tokenToTask.get(token);
+      if (producerTask) {
+        state[token] = live.state.tasks[producerTask]?.data;
+      } else {
+        state[token] = void 0;
+      }
+    }
+    return state;
+  }
+  async function runPipeline(taskName, callbackToken, update) {
+    const taskConfig = live.config.tasks[taskName];
+    const handlerNames = taskConfig.taskHandlers ?? [];
+    const upstreamState = resolveUpstreamState(taskName);
+    for (const handlerName of handlerNames) {
+      const handler = handlers.get(handlerName);
+      if (!handler) {
+        throw new Error(`Handler '${handlerName}' not found in registry (task '${taskName}')`);
+      }
+      const input = {
+        nodeId: taskName,
+        state: upstreamState,
+        taskState: live.state.tasks[taskName],
+        config: taskConfig,
+        callbackToken,
+        update
+      };
+      const status = await handler(input);
+      if (status === "task-initiate-failure") {
+        throw new Error(`Handler '${handlerName}' returned task-initiate-failure (task '${taskName}')`);
+      }
+    }
+  }
+  function dispatchTask(taskName) {
+    const taskConfig = live.config.tasks[taskName];
+    const handlerNames = taskConfig?.taskHandlers;
+    if (!handlerNames || handlerNames.length === 0) {
+      return;
+    }
+    internalJournal.append({
+      type: "task-started",
+      taskName,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    drain();
+    const callbackToken = encodeCallbackToken(taskName);
+    runPipeline(taskName, callbackToken).catch((error) => {
+      if (disposed) return;
+      internalJournal.append({
+        type: "task-failed",
+        taskName,
+        error: error.message ?? String(error),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      drain();
+    });
+  }
+  return {
+    push(event) {
+      if (disposed) return;
+      if (event.type === "task-completed" && event.data && !event.dataHash) {
+        event = { ...event, dataHash: computeDataHash(event.data) };
+      }
+      inputQueue.append(event);
+      drain();
+    },
+    pushAll(events) {
+      if (disposed) return;
+      for (const event of events) {
+        if (event.type === "task-completed" && event.data && !event.dataHash) {
+          inputQueue.append({ ...event, dataHash: computeDataHash(event.data) });
+        } else {
+          inputQueue.append(event);
+        }
+      }
+      drain();
+    },
+    resolveCallback(callbackToken, data, errors) {
+      if (disposed) return;
+      const decoded = decodeCallbackToken(callbackToken);
+      if (!decoded) return;
+      const { taskName } = decoded;
+      if (!live.config.tasks[taskName]) return;
+      if (errors && errors.length > 0) {
+        inputQueue.append({
+          type: "task-failed",
+          taskName,
+          error: errors.join("; "),
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      } else {
+        const dataHash = data && Object.keys(data).length > 0 ? computeDataHash(data) : void 0;
+        inputQueue.append({
+          type: "task-completed",
+          taskName,
+          data,
+          dataHash,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      drain();
+    },
+    addNode(name, taskConfig) {
+      if (disposed) return;
+      inputQueue.append({ type: "task-upsert", taskName: name, taskConfig, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      drain();
+    },
+    removeNode(name) {
+      if (disposed) return;
+      inputQueue.append({ type: "task-removal", taskName: name, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      drain();
+    },
+    addRequires(nodeName, tokens) {
+      if (disposed) return;
+      inputQueue.append({ type: "node-requires-add", nodeName, tokens, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      drain();
+    },
+    removeRequires(nodeName, tokens) {
+      if (disposed) return;
+      inputQueue.append({ type: "node-requires-remove", nodeName, tokens, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      drain();
+    },
+    addProvides(nodeName, tokens) {
+      if (disposed) return;
+      inputQueue.append({ type: "node-provides-add", nodeName, tokens, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      drain();
+    },
+    removeProvides(nodeName, tokens) {
+      if (disposed) return;
+      inputQueue.append({ type: "node-provides-remove", nodeName, tokens, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+      drain();
+    },
+    registerHandler(name, fn) {
+      handlers.set(name, fn);
+    },
+    unregisterHandler(name) {
+      handlers.delete(name);
+    },
+    retrigger(taskName) {
+      if (disposed) return;
+      if (!live.config.tasks[taskName]) return;
+      inputQueue.append({
+        type: "task-restart",
+        taskName,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      drain();
+    },
+    retriggerAll(taskNames) {
+      if (disposed) return;
+      for (const name of taskNames) {
+        if (!live.config.tasks[name]) continue;
+        inputQueue.append({
+          type: "task-restart",
+          taskName: name,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      drain();
+    },
+    snapshot() {
+      return snapshot(live);
+    },
+    getState() {
+      return live;
+    },
+    getSchedule() {
+      return schedule(live);
+    },
+    dispose() {
+      disposed = true;
+    }
+  };
+}
+
+// src/card-compute/index.ts
+function deepGet(obj, path2) {
+  if (!path2 || !obj) return void 0;
+  const parts = path2.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length; i++) {
+    if (cur == null) return void 0;
+    cur = cur[parts[i]];
+  }
+  return cur;
+}
+function deepSet(obj, path2, value) {
+  const parts = path2.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur[parts[i]] == null || typeof cur[parts[i]] !== "object") cur[parts[i]] = {};
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+async function run(node, options) {
+  if (!node?.compute?.length) return node;
+  if (!node.card_data) node.card_data = {};
+  node.computed_values = {};
+  node._sourcesData = options?.sourcesData ?? {};
+  const ctx = {
+    card_data: node.card_data,
+    requires: node.requires ?? {},
+    fetched_sources: node._sourcesData,
+    computed_values: node.computed_values
+  };
+  for (const step of node.compute) {
+    try {
+      const val = await jsonata2(step.expr).evaluate(ctx);
+      deepSet(node.computed_values, step.bindTo, val);
+      ctx.computed_values = node.computed_values;
+    } catch (err) {
+      console.error(`CardCompute.run error on "${node.id ?? "?"}.${step.bindTo}":`, err);
+    }
+  }
+  return node;
+}
+async function evalExpr(expr, node) {
+  const ctx = {
+    card_data: node.card_data ?? {},
+    requires: node.requires ?? {},
+    fetched_sources: node._sourcesData ?? {},
+    computed_values: node.computed_values ?? {}
+  };
+  return jsonata2(expr).evaluate(ctx);
+}
+function resolve(node, path2) {
+  if (path2.startsWith("fetched_sources.")) {
+    return deepGet(node._sourcesData ?? {}, path2.slice("fetched_sources.".length));
+  }
+  return deepGet(node, path2);
+}
+var VALID_ELEMENT_KINDS = /* @__PURE__ */ new Set([
+  "metric",
+  "table",
+  "chart",
+  "form",
+  "filter",
+  "list",
+  "notes",
+  "todo",
+  "alert",
+  "narrative",
+  "badge",
+  "text",
+  "markdown",
+  "custom"
+]);
+var ALLOWED_KEYS = /* @__PURE__ */ new Set(["id", "meta", "requires", "provides", "view", "card_data", "compute", "sources"]);
+function validateNode(node) {
+  const errors = [];
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return { ok: false, errors: ["Node must be a non-null object"] };
+  }
+  const n = node;
+  if (typeof n.id !== "string" || !n.id) errors.push("id: required, must be a non-empty string");
+  for (const key of Object.keys(n)) {
+    if (!ALLOWED_KEYS.has(key)) errors.push(`Unknown top-level key: "${key}"`);
+  }
+  if (n.card_data == null || typeof n.card_data !== "object" || Array.isArray(n.card_data)) {
+    errors.push("card_data: required, must be an object");
+  }
+  if (n.meta != null) {
+    if (typeof n.meta !== "object" || Array.isArray(n.meta)) {
+      errors.push("meta: must be an object");
+    } else {
+      const meta = n.meta;
+      if (meta.title != null && typeof meta.title !== "string") errors.push("meta.title: must be a string");
+      if (meta.tags != null && !Array.isArray(meta.tags)) errors.push("meta.tags: must be an array");
+    }
+  }
+  if (n.requires != null && !Array.isArray(n.requires)) errors.push("requires: must be an array of strings");
+  if (n.provides != null) {
+    if (!Array.isArray(n.provides)) {
+      errors.push("provides: must be an array of { bindTo, src } bindings");
+    } else {
+      n.provides.forEach((p, i) => {
+        if (!p || typeof p !== "object" || Array.isArray(p)) {
+          errors.push(`provides[${i}]: must be an object with bindTo and src`);
+        } else {
+          const b = p;
+          if (typeof b.bindTo !== "string" || !b.bindTo) errors.push(`provides[${i}]: missing required "bindTo" string`);
+          if (typeof b.src !== "string" || !b.src) errors.push(`provides[${i}]: missing required "src" string`);
+        }
+      });
+    }
+  }
+  if (n.compute != null) {
+    if (!Array.isArray(n.compute)) {
+      errors.push("compute: must be an array of compute steps");
+    } else {
+      n.compute.forEach((step, i) => {
+        if (!step || typeof step !== "object" || Array.isArray(step)) {
+          errors.push(`compute[${i}]: must be a compute step object`);
+        } else {
+          const s = step;
+          if (typeof s.bindTo !== "string" || !s.bindTo) errors.push(`compute[${i}]: missing required "bindTo" property`);
+          if (typeof s.expr !== "string" || !s.expr) errors.push(`compute[${i}]: missing required "expr" string (JSONata expression)`);
+        }
+      });
+    }
+  }
+  if (n.sources != null) {
+    if (!Array.isArray(n.sources)) {
+      errors.push("sources: must be an array");
+    } else {
+      n.sources.forEach((src, i) => {
+        if (!src || typeof src !== "object" || Array.isArray(src)) {
+          errors.push(`sources[${i}]: must be an object`);
+        } else {
+          const s = src;
+          if (typeof s.bindTo !== "string" || !s.bindTo) errors.push(`sources[${i}]: missing required "bindTo" property`);
+          if (s.outputFile != null && typeof s.outputFile !== "string") errors.push(`sources[${i}]: outputFile must be a string`);
+          if (s.optionalForCompletionGating != null && typeof s.optionalForCompletionGating !== "boolean") {
+            errors.push(`sources[${i}]: optionalForCompletionGating must be a boolean`);
+          }
+        }
+      });
+    }
+  }
+  if (n.view != null) {
+    if (typeof n.view !== "object" || Array.isArray(n.view)) {
+      errors.push("view: must be an object");
+    } else {
+      const view = n.view;
+      if (!Array.isArray(view.elements) || view.elements.length === 0) {
+        errors.push("view.elements: required, must be a non-empty array");
+      } else {
+        view.elements.forEach((elem, i) => {
+          if (!elem || typeof elem !== "object") {
+            errors.push(`view.elements[${i}]: must be an object`);
+            return;
+          }
+          if (!elem.kind || typeof elem.kind !== "string") {
+            errors.push(`view.elements[${i}].kind: required, must be a string`);
+          } else if (!VALID_ELEMENT_KINDS.has(elem.kind)) {
+            errors.push(`view.elements[${i}].kind: unknown kind "${elem.kind}". Valid: ${[...VALID_ELEMENT_KINDS].join(", ")}`);
+          }
+          if (elem.data != null && (typeof elem.data !== "object" || Array.isArray(elem.data))) {
+            errors.push(`view.elements[${i}].data: must be an object`);
+          }
+        });
+      }
+      if (view.layout != null && (typeof view.layout !== "object" || Array.isArray(view.layout))) errors.push("view.layout: must be an object");
+      if (view.features != null && (typeof view.features !== "object" || Array.isArray(view.features))) errors.push("view.features: must be an object");
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+function enrichSources(sources, context) {
+  if (!sources || sources.length === 0) return [];
+  return sources.map((src) => ({
+    ...src,
+    _requires: context.requires ?? {},
+    _sourcesData: context.sourcesData ?? {},
+    _computed_values: context.computed_values ?? {}
+  }));
+}
+var CardCompute = {
+  run,
+  eval: evalExpr,
+  resolve,
+  validate: validateNode,
+  enrichSources
+};
+
+// src/cli/board-live-cards-cli.ts
+var BOARD_FILE = "board-graph.json";
+var JOURNAL_FILE = "board-journal.jsonl";
+var TASK_EXECUTOR_LOG_FILE = "task-executor.jsonl";
+var INVENTORY_FILE = "cards-inventory.jsonl";
+var RUNTIME_OUT_FILE = ".runtime-out";
+var DEFAULT_RUNTIME_OUT_DIR = "runtime-out";
+var RUNTIME_STATUS_FILE = "board-livegraph-status.json";
+var RUNTIME_CARDS_DIR = "cards";
+var RUNTIME_DATA_OBJECTS_DIR = "data-objects";
+var EMPTY_CONFIG = { settings: { completion: "manual", refreshStrategy: "data-changed" }, tasks: {} };
+var BoardJournal = class {
+  journalPath;
+  lastDrainedId;
+  constructor(journalPath, lastDrainedJournalId) {
+    this.journalPath = journalPath;
+    this.lastDrainedId = lastDrainedJournalId;
+  }
+  append(event) {
+    const entry = { id: randomUUID(), event };
+    fs.appendFileSync(this.journalPath, JSON.stringify(entry) + "\n", "utf-8");
+  }
+  drain() {
+    if (!fs.existsSync(this.journalPath)) return [];
+    const content = fs.readFileSync(this.journalPath, "utf-8").trim();
+    if (!content) return [];
+    const entries = content.split("\n").map((l) => JSON.parse(l));
+    let startIdx = 0;
+    if (this.lastDrainedId) {
+      const drainedIdx = entries.findIndex((e) => e.id === this.lastDrainedId);
+      if (drainedIdx !== -1) startIdx = drainedIdx + 1;
+    }
+    const undrained = entries.slice(startIdx);
+    if (undrained.length > 0) {
+      this.lastDrainedId = undrained[undrained.length - 1].id;
+    }
+    return undrained.map((e) => e.event);
+  }
+  get size() {
+    if (!fs.existsSync(this.journalPath)) return 0;
+    const content = fs.readFileSync(this.journalPath, "utf-8").trim();
+    if (!content) return 0;
+    const entries = content.split("\n").map((l) => JSON.parse(l));
+    if (!this.lastDrainedId) return entries.length;
+    const drainedIdx = entries.findIndex((e) => e.id === this.lastDrainedId);
+    return drainedIdx === -1 ? entries.length : entries.length - drainedIdx - 1;
+  }
+  get lastDrainedJournalId() {
+    return this.lastDrainedId;
+  }
+};
+function readCardInventory(boardDir) {
+  const inventoryPath = path.join(boardDir, INVENTORY_FILE);
+  if (!fs.existsSync(inventoryPath)) return [];
+  const lines = fs.readFileSync(inventoryPath, "utf-8").split("\n").filter((l) => l.trim());
+  return lines.map((l) => JSON.parse(l));
+}
+function lookupCardPath(boardDir, cardId) {
+  const entries = readCardInventory(boardDir);
+  const entry = entries.find((e) => e.cardId === cardId);
+  return entry?.cardFilePath ?? null;
+}
+function appendCardInventory(boardDir, entry) {
+  const inventoryPath = path.join(boardDir, INVENTORY_FILE);
+  const normalized = { ...entry, cardFilePath: path.resolve(entry.cardFilePath) };
+  fs.appendFileSync(inventoryPath, JSON.stringify(normalized) + "\n");
+}
+function buildCardInventoryIndex(boardDir) {
+  const byCardId = /* @__PURE__ */ new Map();
+  const byCardPath = /* @__PURE__ */ new Map();
+  for (const entry of readCardInventory(boardDir)) {
+    const normalizedPath = path.resolve(entry.cardFilePath);
+    const normalizedEntry = {
+      ...entry,
+      cardFilePath: normalizedPath
+    };
+    const existingById = byCardId.get(entry.cardId);
+    if (existingById && existingById.cardFilePath !== normalizedPath) {
+      throw new Error(
+        `Inventory invariant violation: card id "${entry.cardId}" maps to multiple files: "${existingById.cardFilePath}" and "${normalizedPath}"`
+      );
+    }
+    const existingByPath = byCardPath.get(normalizedPath);
+    if (existingByPath && existingByPath.cardId !== entry.cardId) {
+      throw new Error(
+        `Inventory invariant violation: file "${normalizedPath}" maps to multiple ids: "${existingByPath.cardId}" and "${entry.cardId}"`
+      );
+    }
+    byCardId.set(entry.cardId, normalizedEntry);
+    byCardPath.set(normalizedPath, normalizedEntry);
+  }
+  return { byCardId, byCardPath };
+}
+function initBoard(dir) {
+  const boardPath = path.join(dir, BOARD_FILE);
+  if (fs.existsSync(boardPath)) {
+    const envelope2 = JSON.parse(fs.readFileSync(boardPath, "utf-8"));
+    restore(envelope2.graph);
+    return "exists";
+  }
+  if (fs.existsSync(dir)) {
+    const entries = fs.readdirSync(dir);
+    if (entries.length > 0) {
+      throw new Error(`Directory "${dir}" is not empty and has no valid ${BOARD_FILE}`);
+    }
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  const live = createLiveGraph(EMPTY_CONFIG);
+  const snap = snapshot(live);
+  const envelope = { lastDrainedJournalId: "", graph: snap };
+  fs.writeFileSync(boardPath, JSON.stringify(envelope, null, 2));
+  return "created";
+}
+function loadBoardEnvelope(dir) {
+  const raw = fs.readFileSync(path.join(dir, BOARD_FILE), "utf-8");
+  return JSON.parse(raw);
+}
+function loadBoard(dir) {
+  const envelope = loadBoardEnvelope(dir);
+  return restore(envelope.graph);
+}
+function saveBoard(dir, rg, journal) {
+  const snap = rg.snapshot();
+  const envelope = {
+    lastDrainedJournalId: journal.lastDrainedJournalId,
+    graph: snap
+  };
+  writeJsonAtomic(path.join(dir, BOARD_FILE), envelope);
+  const live = restore(snap);
+  const statusObject = buildBoardStatusObject(dir, live);
+  writeJsonAtomic(resolveStatusSnapshotPath(dir), statusObject);
+}
+function runtimeOutConfigPath(boardDir) {
+  return path.join(boardDir, RUNTIME_OUT_FILE);
+}
+function resolveConfiguredRuntimeOutDir(boardDir) {
+  const cfgPath = runtimeOutConfigPath(boardDir);
+  if (fs.existsSync(cfgPath)) {
+    const configured = fs.readFileSync(cfgPath, "utf-8").trim();
+    if (configured) {
+      return path.isAbsolute(configured) ? configured : path.resolve(boardDir, configured);
+    }
+  }
+  const defaultDir = path.join(boardDir, DEFAULT_RUNTIME_OUT_DIR);
+  fs.writeFileSync(cfgPath, defaultDir, "utf-8");
+  return defaultDir;
+}
+function configureRuntimeOutDir(boardDir, runtimeOut) {
+  let resolved;
+  if (runtimeOut) {
+    resolved = path.isAbsolute(runtimeOut) ? runtimeOut : path.resolve(boardDir, runtimeOut);
+  } else {
+    resolved = path.join(boardDir, DEFAULT_RUNTIME_OUT_DIR);
+  }
+  fs.mkdirSync(resolved, { recursive: true });
+  fs.writeFileSync(runtimeOutConfigPath(boardDir), resolved, "utf-8");
+  return resolved;
+}
+function resolveStatusSnapshotPath(boardDir) {
+  return path.join(resolveConfiguredRuntimeOutDir(boardDir), RUNTIME_STATUS_FILE);
+}
+function resolveComputedValuesPath(boardDir, cardId) {
+  return path.join(resolveConfiguredRuntimeOutDir(boardDir), RUNTIME_CARDS_DIR, `${cardId}.computed.json`);
+}
+function resolveDataObjectsDirPath(boardDir) {
+  return path.join(resolveConfiguredRuntimeOutDir(boardDir), RUNTIME_DATA_OBJECTS_DIR);
+}
+function toDataObjectFileName(token) {
+  return token.replace(/[\\/]/g, "__");
+}
+function writeRuntimeDataObjects(boardDir, data) {
+  for (const [token, payload] of Object.entries(data)) {
+    if (!token) continue;
+    const fileName = toDataObjectFileName(token);
+    if (!fileName) continue;
+    const filePath = path.join(resolveDataObjectsDirPath(boardDir), fileName);
+    writeJsonAtomic(filePath, payload);
+  }
+}
+function writeJsonAtomic(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), "utf-8");
+  fs.renameSync(tmpPath, filePath);
+}
+function withBoardLock(boardDir, fn) {
+  const boardPath = path.join(boardDir, BOARD_FILE);
+  const release = lockSync(boardPath, { retries: { retries: 5, minTimeout: 100 } });
+  try {
+    return fn();
+  } finally {
+    release();
+  }
+}
+function decodeCallbackToken2(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token, "base64url").toString());
+    if (typeof payload?.t === "string") return { taskName: payload.t };
+    return null;
+  } catch {
+    return null;
+  }
+}
+function encodeSourceToken(payload) {
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function decodeSourceToken(token) {
+  try {
+    const p = JSON.parse(Buffer.from(token, "base64url").toString());
+    if (typeof p?.cbk === "string" && typeof p?.cid === "string" && typeof p?.b === "string" && typeof p?.d === "string") {
+      return p;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function runtimePath(boardDir, cardId) {
+  return path.join(boardDir, `${cardId}.runtime.json`);
+}
+function readRuntimeState(boardDir, cardId) {
+  const p = runtimePath(boardDir, cardId);
+  if (!fs.existsSync(p)) return { _sources: {} };
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf-8"));
+  } catch {
+    return { _sources: {} };
+  }
+}
+function writeRuntimeState(boardDir, cardId, state) {
+  fs.writeFileSync(runtimePath(boardDir, cardId), JSON.stringify(state, null, 2));
+}
+function appendEventToJournal(boardDir, event) {
+  const journalPath = path.join(boardDir, JOURNAL_FILE);
+  const entry = { id: randomUUID(), event };
+  fs.appendFileSync(journalPath, JSON.stringify(entry) + "\n", "utf-8");
+}
+function getUndrainedEntries(boardDir, lastDrainedId) {
+  const journalPath = path.join(boardDir, JOURNAL_FILE);
+  if (!fs.existsSync(journalPath)) return [];
+  const content = fs.readFileSync(journalPath, "utf-8").trim();
+  if (!content) return [];
+  const entries = content.split("\n").map((l) => JSON.parse(l));
+  if (!lastDrainedId) return entries;
+  const idx = entries.findIndex((e) => e.id === lastDrainedId);
+  return idx === -1 ? entries : entries.slice(idx + 1);
+}
+function determineLatestPendingAccumulated(boardDir) {
+  const boardPath = path.join(boardDir, BOARD_FILE);
+  if (!fs.existsSync(boardPath)) return 0;
+  try {
+    const envelope = loadBoardEnvelope(boardDir);
+    return getUndrainedEntries(boardDir, envelope.lastDrainedJournalId).length;
+  } catch {
+    return 0;
+  }
+}
+function shouldUseShellForCommand(cmd, forceShell) {
+  if (typeof forceShell === "boolean") return forceShell;
+  return process.platform === "win32" && /\.(cmd|bat)$/i.test(cmd);
+}
+var _gitBashPath;
+var GIT_BASH_CACHE_FILE = path.join(os.tmpdir(), ".board-live-cards-git-bash-cache.json");
+function findGitBash() {
+  if (_gitBashPath !== void 0) return _gitBashPath;
+  if (process.platform !== "win32") return _gitBashPath = false;
+  try {
+    const cached = JSON.parse(fs.readFileSync(GIT_BASH_CACHE_FILE, "utf8"));
+    if (cached.path === false || typeof cached.path === "string" && fs.existsSync(cached.path)) {
+      return _gitBashPath = cached.path;
+    }
+  } catch {
+  }
+  const candidates = [
+    process.env.SHELL,
+    process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Git", "usr", "bin", "bash.exe"),
+    process.env.PROGRAMFILES && path.join(process.env.PROGRAMFILES, "Git", "bin", "bash.exe"),
+    process.env["PROGRAMFILES(X86)"] && path.join(process.env["PROGRAMFILES(X86)"], "Git", "bin", "bash.exe"),
+    process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, "Programs", "Git", "bin", "bash.exe")
+  ];
+  for (const c of candidates) {
+    if (c && /bash(\.exe)?$/i.test(c) && fs.existsSync(c)) {
+      _gitBashPath = c;
+      try {
+        fs.writeFileSync(GIT_BASH_CACHE_FILE, JSON.stringify({ path: c }));
+      } catch {
+      }
+      return _gitBashPath;
+    }
+  }
+  _gitBashPath = false;
+  try {
+    fs.writeFileSync(GIT_BASH_CACHE_FILE, JSON.stringify({ path: false }));
+  } catch {
+  }
+  return _gitBashPath;
+}
+function shellQuote(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function spawnDetachedCommand(cmd, args) {
+  if (process.platform === "win32") {
+    const bash = findGitBash();
+    if (bash) {
+      const shellCmd = [cmd, ...args].map((a) => shellQuote(a.replace(/\\/g, "/"))).join(" ");
+      const child3 = spawn(bash, ["-c", shellCmd], { detached: true, stdio: "ignore", windowsHide: true });
+      child3.unref();
+      return;
+    }
+    const child2 = spawn("cmd", ["/c", "start", "/b", "", cmd, ...args], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child2.unref();
+    return;
+  }
+  const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+  child.unref();
+}
+function execCommandSync(cmd, args, options) {
+  const output = execFileSync(cmd, args, {
+    shell: shouldUseShellForCommand(cmd, options?.shell),
+    timeout: options?.timeout,
+    encoding: options?.encoding,
+    cwd: options?.cwd,
+    windowsHide: true,
+    env: options?.env
+  });
+  return typeof output === "string" ? output : output.toString("utf-8");
+}
+function execCommandAsync(cmd, args, callback) {
+  execFile(
+    cmd,
+    args,
+    { shell: shouldUseShellForCommand(cmd), encoding: "utf8", windowsHide: true },
+    (err, stdout, stderr) => callback(err ?? null, stdout, stderr)
+  );
+}
+function splitCommandLine(command) {
+  const tokens = [];
+  let current = "";
+  let quote = null;
+  for (const ch of command.trim()) {
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (/\s/.test(ch)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (quote) {
+    throw new Error(`Unterminated quote in command: ${command}`);
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+function spawnDetachedProcessAccumulatedWorker(boardDir) {
+  const { cmd, args: cliArgs } = getCliInvocation("process-accumulated-events", ["--rg", boardDir, "--inline-loop"]);
+  try {
+    spawnDetachedCommand(cmd, cliArgs);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function processAccumulatedEventsInlineLoop(boardDir, settleDelayMs = 50) {
+  while (determineLatestPendingAccumulated(boardDir) > 0) {
+    const ran = processAccumulatedEvents(boardDir);
+    if (!ran) return false;
+    await new Promise((resolve3) => setTimeout(resolve3, settleDelayMs));
+  }
+  return true;
+}
+function shouldAvoidDetachedProcessSpawn() {
+  return process.env.BOARD_LIVE_CARDS_NO_SPAWN === "1";
+}
+function processAccumulatedEvents(boardDir) {
+  const boardPath = path.join(boardDir, BOARD_FILE);
+  let release;
+  try {
+    release = lockSync(boardPath, { retries: 0 });
+  } catch {
+    return false;
+  }
+  try {
+    const { rg, journal } = createBoardReactiveGraph(boardDir);
+    const undrained = journal.drain();
+    rg.pushAll(undrained);
+    saveBoard(boardDir, rg, journal);
+    rg.dispose();
+    return true;
+  } finally {
+    release();
+  }
+}
+async function processAccumulatedEventsInfinitePass(boardDir, settleDelayMs = 50, options) {
+  if (options?.inlineLoop || shouldAvoidDetachedProcessSpawn()) {
+    return processAccumulatedEventsInlineLoop(boardDir, settleDelayMs);
+  }
+  return spawnDetachedProcessAccumulatedWorker(boardDir);
+}
+async function processAccumulatedEventsForced(boardDir, options) {
+  processAccumulatedEvents(boardDir);
+  await processAccumulatedEventsInfinitePass(boardDir, 50, options);
+}
+function liveCardToTaskConfig(card) {
+  const requires = card.requires;
+  const provides = card.provides?.map((p) => p.bindTo) ?? [];
+  return {
+    requires: requires && requires.length > 0 ? requires : void 0,
+    provides,
+    taskHandlers: ["card-handler"],
+    description: card.meta?.title ?? card.id
+  };
+}
+var __dirname$1 = path.dirname(fileURLToPath(import.meta.url));
+var REPO_ROOT = path.resolve(__dirname$1, "..", "..");
+var LOCAL_TSX_CLI = path.join(REPO_ROOT, "node_modules", "tsx", "dist", "cli.mjs");
+function getCliInvocation(command, args) {
+  const jsPath = path.join(__dirname$1, "board-live-cards-cli.js");
+  if (fs.existsSync(jsPath)) {
+    return { cmd: process.execPath, args: [jsPath, command, ...args] };
+  }
+  const tsPath = path.join(__dirname$1, "board-live-cards-cli.ts");
+  if (fs.existsSync(tsPath) && fs.existsSync(LOCAL_TSX_CLI)) {
+    return { cmd: process.execPath, args: [LOCAL_TSX_CLI, tsPath, command, ...args] };
+  }
+  const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
+  return { cmd: npxCmd, args: ["tsx", tsPath, command, ...args] };
+}
+function invokeRunSources(boardDir, cardPath, callbackToken, callback) {
+  const { cmd, args } = getCliInvocation("run-sources-internal", ["--card", cardPath, "--token", callbackToken, "--rg", boardDir]);
+  try {
+    spawnDetachedCommand(cmd, args);
+    callback(null);
+  } catch (err) {
+    callback(err instanceof Error ? err : new Error(String(err)));
+  }
+}
+function appendTaskExecutorLog(boardDir, hydratedSource) {
+  try {
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      hydratedSource
+    };
+    fs.appendFileSync(path.join(boardDir, TASK_EXECUTOR_LOG_FILE), JSON.stringify(entry) + "\n", "utf-8");
+  } catch (logErr) {
+    console.error(`[task-executor-log] append failed: ${logErr instanceof Error ? logErr.message : String(logErr)}`);
+  }
+}
+function invokeSourceDataFetched(sourceToken, tmpFile, callback) {
+  const { cmd, args } = getCliInvocation("source-data-fetched", ["--tmp", tmpFile, "--token", sourceToken]);
+  execCommandAsync(cmd, args, (err, stdout, stderr) => {
+    if (err) console.error(`[source-data-fetched] call failed:`, err.message);
+    if (stdout) console.log(stdout.trim());
+    if (stderr) console.error(stderr.trim());
+  });
+}
+function invokeSourceDataFetchFailure(sourceToken, reason, callback) {
+  const { cmd, args } = getCliInvocation("source-data-fetch-failure", ["--token", sourceToken, "--reason", reason]);
+  execCommandAsync(cmd, args, (err) => callback(err));
+}
+function createBoardReactiveGraph(boardDir) {
+  const envelope = loadBoardEnvelope(boardDir);
+  const live = restore(envelope.graph);
+  const journalPath = path.join(boardDir, JOURNAL_FILE);
+  const journal = new BoardJournal(journalPath, envelope.lastDrainedJournalId);
+  const handlers = {
+    "card-handler": async (input) => {
+      const cardPath = lookupCardPath(boardDir, input.nodeId);
+      if (!cardPath) return "task-initiate-failure";
+      const card = JSON.parse(fs.readFileSync(cardPath, "utf-8"));
+      const cardId = card.id;
+      const cardState = card.card_data ?? {};
+      const allSources = card.sources ?? [];
+      const requiredSources = allSources.filter((s) => s.optionalForCompletionGating !== true);
+      const runtime = readRuntimeState(boardDir, cardId);
+      let runtimeDirty = false;
+      if (input.update) {
+        const u = input.update;
+        const bindTo = u.bindTo;
+        if (!runtime._sources[bindTo]) runtime._sources[bindTo] = {};
+        if (u.failure) {
+          runtime._sources[bindTo].lastError = u.reason ?? "unknown";
+          delete runtime._sources[bindTo].lastFetchedAt;
+          runtimeDirty = true;
+          console.log(`[card-handler] source "${bindTo}" fetch failed: ${runtime._sources[bindTo].lastError}`);
+        } else {
+          runtime._sources[bindTo].lastFetchedAt = u.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+          delete runtime._sources[bindTo].lastError;
+          runtimeDirty = true;
+          console.log(`[card-handler] source "${bindTo}" delivered \u2192 ${u.dest}`);
+        }
+        if (runtimeDirty) writeRuntimeState(boardDir, cardId, runtime);
+      }
+      const sourcesData = {};
+      for (const src of allSources) {
+        if (src.outputFile) {
+          const filePath = path.join(boardDir, src.outputFile);
+          if (fs.existsSync(filePath)) {
+            const raw = fs.readFileSync(filePath, "utf-8").trim();
+            try {
+              sourcesData[src.bindTo] = JSON.parse(raw);
+            } catch {
+              sourcesData[src.bindTo] = raw;
+            }
+          }
+        }
+      }
+      const requires = {};
+      for (const [token, taskData] of Object.entries(input.state ?? {})) {
+        if (taskData !== null && typeof taskData === "object" && !Array.isArray(taskData)) {
+          const unwrapped = taskData[token];
+          requires[token] = unwrapped !== void 0 ? unwrapped : taskData;
+        } else {
+          requires[token] = taskData;
+        }
+      }
+      const computeNode = {
+        id: cardId,
+        card_data: { ...cardState },
+        requires,
+        sources: allSources,
+        compute: card.compute
+      };
+      computeNode._sourcesData = sourcesData;
+      if (card.compute) {
+        await CardCompute.run(computeNode, { sourcesData });
+      }
+      const cvPath = resolveComputedValuesPath(boardDir, cardId);
+      writeJsonAtomic(cvPath, {
+        schema_version: "v1",
+        card_id: cardId,
+        computed_values: computeNode.computed_values ?? {}
+      });
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const undeliveredRequired = requiredSources.filter((s) => {
+        if (!s.outputFile) return false;
+        const entry = runtime._sources[s.bindTo];
+        if (!entry?.lastRequestedAt) return true;
+        if (!entry.lastFetchedAt) return true;
+        return entry.lastFetchedAt <= entry.lastRequestedAt;
+      });
+      if (undeliveredRequired.length > 0) {
+        let stampedAny = false;
+        for (const src of undeliveredRequired) {
+          const entry = runtime._sources[src.bindTo] ?? {};
+          if (!entry.lastRequestedAt || entry.lastFetchedAt && entry.lastFetchedAt >= entry.lastRequestedAt) {
+            entry.lastRequestedAt = now;
+            runtime._sources[src.bindTo] = entry;
+            stampedAny = true;
+          }
+        }
+        if (stampedAny) writeRuntimeState(boardDir, cardId, runtime);
+        const enrichedCard = { ...card };
+        const enrichedSources = CardCompute.enrichSources(
+          Array.isArray(card.sources) ? card.sources : void 0,
+          {
+            requires,
+            sourcesData,
+            computed_values: computeNode.computed_values
+          }
+        );
+        const sourceCwd = path.dirname(cardPath);
+        enrichedCard.sources = Array.isArray(enrichedSources) ? enrichedSources.map((src) => ({
+          ...src,
+          cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : sourceCwd,
+          boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
+        })) : enrichedSources;
+        const enrichedCardPath = path.join(os.tmpdir(), `card-enriched-${cardId}-${Date.now()}.json`);
+        fs.writeFileSync(enrichedCardPath, JSON.stringify(enrichedCard, null, 2), "utf-8");
+        invokeRunSources(boardDir, enrichedCardPath, input.callbackToken, (err) => {
+          if (err) {
+            console.error(`[card-handler] ${input.nodeId}:`, err.message);
+            try {
+              fs.unlinkSync(enrichedCardPath);
+            } catch {
+            }
+          }
+        });
+        return "task-initiated";
+      }
+      const providesBindings = card.provides ?? [];
+      const data = {};
+      for (const { bindTo, src } of providesBindings) {
+        data[bindTo] = CardCompute.resolve(computeNode, src);
+      }
+      writeRuntimeDataObjects(boardDir, data);
+      const undeliveredOptional = allSources.filter((s) => {
+        if (s.optionalForCompletionGating !== true || !s.outputFile) return false;
+        const entry = runtime._sources[s.bindTo];
+        if (!entry?.lastRequestedAt) return true;
+        if (!entry.lastFetchedAt) return true;
+        return entry.lastFetchedAt <= entry.lastRequestedAt;
+      });
+      if (undeliveredOptional.length > 0) {
+        invokeRunSources(boardDir, cardPath, input.callbackToken, (err) => {
+          if (err) console.error(`[card-handler] ${input.nodeId}:`, err.message);
+        });
+      }
+      appendEventToJournal(boardDir, {
+        type: "task-completed",
+        taskName: input.nodeId,
+        data,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      return "task-initiated";
+    }
+  };
+  const rg = createReactiveGraph(live, { handlers });
+  return { rg, journal };
+}
+function addSingleCardFromFile(dir, cardFile) {
+  const absCardPath = path.resolve(cardFile);
+  if (!fs.existsSync(absCardPath)) {
+    throw new Error(`Card file not found: ${absCardPath}`);
+  }
+  let card;
+  try {
+    card = JSON.parse(fs.readFileSync(absCardPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Failed to parse card file: ${absCardPath} - ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!card.id) {
+    throw new Error('Card JSON must have an "id" field');
+  }
+  const existing = readCardInventory(dir);
+  if (existing.some((e) => e.cardId === card.id)) {
+    throw new Error(`Card "${card.id}" already exists in inventory`);
+  }
+  appendCardInventory(dir, {
+    cardId: card.id,
+    cardFilePath: absCardPath,
+    addedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const taskConfig = liveCardToTaskConfig(card);
+  appendEventToJournal(dir, {
+    type: "task-upsert",
+    taskName: card.id,
+    taskConfig,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  console.log(`Card "${card.id}" added to board at ${path.resolve(dir)} (drain scheduled)`);
+  console.log(`  taskHandlers: [${taskConfig.taskHandlers?.join(", ") ?? ""}]`);
+  console.log(`  provides: [${taskConfig.provides.join(", ")}]`);
+  if (taskConfig.requires) console.log(`  requires: [${taskConfig.requires.join(", ")}]`);
+}
+function resolveCardGlobMatches(cardGlob) {
+  const patterns = cardGlob.split(",").map((s) => s.trim()).filter(Boolean).map((p) => p.replace(/\\/g, "/"));
+  const matches = fg.sync(patterns, {
+    absolute: true,
+    onlyFiles: true,
+    unique: true,
+    dot: false
+  });
+  return [...matches].map((m) => path.resolve(m)).sort((a, b) => a.localeCompare(b));
+}
+function cmdAddCards(args) {
+  const rgIdx = args.indexOf("--rg");
+  const cardIdx = args.indexOf("--card");
+  const globIdx = args.indexOf("--card-glob");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const cardFile = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
+  const cardGlob = globIdx !== -1 ? args[globIdx + 1] : void 0;
+  if (!dir || !cardFile && !cardGlob || cardFile && cardGlob) {
+    throw new Error("Usage: board-live-cards add-cards --rg <dir> (--card <card.json> | --card-glob <glob>)");
+  }
+  if (cardFile) {
+    addSingleCardFromFile(dir, cardFile);
+  } else {
+    const matches = resolveCardGlobMatches(cardGlob);
+    if (matches.length === 0) {
+      throw new Error(`No card files matched glob: ${cardGlob}`);
+    }
+    for (const match of matches) {
+      addSingleCardFromFile(dir, match);
+    }
+    console.log(`Added ${matches.length} cards from glob: ${cardGlob}`);
+  }
+  void processAccumulatedEventsInfinitePass(dir);
+}
+function cmdInit(args) {
+  const dir = args[0];
+  if (!dir) {
+    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--runtime-out <dir>]");
+  }
+  const teIdx = args.indexOf("--task-executor");
+  const taskExecutor = teIdx !== -1 ? args[teIdx + 1] : void 0;
+  const chIdx = args.indexOf("--chat-handler");
+  const chatHandler = chIdx !== -1 ? args[chIdx + 1] : void 0;
+  const roIdx = args.indexOf("--runtime-out");
+  const runtimeOut = roIdx !== -1 ? args[roIdx + 1] : void 0;
+  if (roIdx !== -1 && !runtimeOut) {
+    throw new Error("Usage: board-live-cards init <dir> [--task-executor <script>] [--chat-handler <script>] [--runtime-out <dir>]");
+  }
+  const result = initBoard(dir);
+  if (taskExecutor) {
+    fs.writeFileSync(path.join(dir, ".task-executor"), taskExecutor, "utf-8");
+  }
+  if (chatHandler) {
+    fs.writeFileSync(path.join(dir, ".chat-handler"), chatHandler, "utf-8");
+  }
+  const runtimeOutDir = configureRuntimeOutDir(dir, runtimeOut);
+  const live = loadBoard(dir);
+  writeJsonAtomic(resolveStatusSnapshotPath(dir), buildBoardStatusObject(dir, live));
+  if (result === "exists") {
+    console.log(`Board already initialized at ${path.resolve(dir)}${taskExecutor ? ` (task-executor updated: ${taskExecutor})` : ""} (runtime-out: ${runtimeOutDir})`);
+  } else {
+    console.log(`Board initialized at ${path.resolve(dir)}${taskExecutor ? ` (task-executor: ${taskExecutor})` : ""} (runtime-out: ${runtimeOutDir})`);
+  }
+}
+function buildBoardStatusObject(dir, live) {
+  const taskState = live.state.tasks;
+  const taskConfig = live.config.tasks;
+  const cardNames = Object.keys(taskState);
+  const sched = schedule(live);
+  const statusCounts = {
+    completed: 0,
+    failed: 0,
+    in_progress: 0,
+    pending: 0,
+    blocked: 0,
+    unresolved: 0
+  };
+  const waitingByCard = /* @__PURE__ */ new Map();
+  for (const p of sched.pending) waitingByCard.set(p.taskName, p.waitingOn);
+  for (const u of sched.unresolved) waitingByCard.set(u.taskName, u.missingTokens);
+  for (const b of sched.blocked) waitingByCard.set(b.taskName, b.failedTokens);
+  const dependentsByToken = /* @__PURE__ */ new Map();
+  for (const [name, cfg] of Object.entries(taskConfig)) {
+    for (const token of cfg.requires ?? []) {
+      const dependents = dependentsByToken.get(token) ?? [];
+      dependents.push(name);
+      dependentsByToken.set(token, dependents);
+    }
+  }
+  const cards = cardNames.sort().map((name) => {
+    const state = taskState[name];
+    const cfg = taskConfig[name] ?? { requires: [], provides: [] };
+    if (state.status === "completed") statusCounts.completed += 1;
+    else if (state.status === "failed") statusCounts.failed += 1;
+    else if (state.status === "in-progress") statusCounts.in_progress += 1;
+    const requires = cfg.requires ?? [];
+    const provides = cfg.provides ?? [];
+    const runtimeKeys = Object.keys(state.data ?? {}).sort();
+    const requiresSatisfied = requires.filter((token) => live.state.availableOutputs.includes(token));
+    const requiresMissing = requires.filter((token) => !live.state.availableOutputs.includes(token));
+    const blockedBy = waitingByCard.get(name) ?? requiresMissing;
+    const unblocks = /* @__PURE__ */ new Set();
+    for (const token of provides) {
+      for (const dependent of dependentsByToken.get(token) ?? []) {
+        if (dependent !== name) unblocks.add(dependent);
+      }
+    }
+    const lastFailureAt = state.failedAt;
+    const error = state.error ? {
+      message: state.error,
+      code: "TASK_FAILED",
+      at: lastFailureAt,
+      source: "task-runtime"
+    } : void 0;
+    return {
+      name,
+      status: state.status,
+      error,
+      requires,
+      requires_satisfied: requiresSatisfied,
+      requires_missing: requiresMissing,
+      provides_declared: provides,
+      provides_runtime: runtimeKeys,
+      blocked_by: blockedBy,
+      unblocks: Array.from(unblocks).sort(),
+      runtime: {
+        attempt_count: state.executionCount ?? 0,
+        restart_count: state.retryCount ?? 0,
+        in_progress_since: state.status === "in-progress" ? state.startedAt ?? null : null,
+        last_transition_at: state.lastUpdated ?? null,
+        last_completed_at: state.completedAt ?? null,
+        last_restarted_at: state.startedAt ?? null,
+        status_age_ms: state.lastUpdated ? Math.max(0, Date.now() - Date.parse(state.lastUpdated)) : null
+      }
+    };
+  });
+  statusCounts.pending = sched.pending.length;
+  statusCounts.blocked = sched.blocked.length;
+  statusCounts.unresolved = sched.unresolved.length;
+  const fanOut = cards.map((c) => ({ name: c.name, fanOut: c.unblocks.length })).sort((a, b) => b.fanOut - a.fanOut || a.name.localeCompare(b.name));
+  const maxFanOut = fanOut.length > 0 ? fanOut[0] : { name: null, fanOut: 0 };
+  const allRequires = /* @__PURE__ */ new Set();
+  for (const cfg of Object.values(taskConfig)) {
+    for (const r of cfg.requires ?? []) allRequires.add(r);
+  }
+  let orphanCards = 0;
+  for (const [name, cfg] of Object.entries(taskConfig)) {
+    const requiresNone = (cfg.requires ?? []).length === 0;
+    const provides = cfg.provides ?? [];
+    const feedsAny = provides.some((p) => (dependentsByToken.get(p) ?? []).some((d) => d !== name));
+    if (requiresNone && !feedsAny) orphanCards += 1;
+  }
+  return {
+    schema_version: "v1",
+    meta: {
+      board: {
+        path: path.resolve(dir)
+      }
+    },
+    summary: {
+      card_count: cardNames.length,
+      completed: statusCounts.completed,
+      eligible: sched.eligible.length,
+      pending: statusCounts.pending,
+      blocked: statusCounts.blocked,
+      unresolved: statusCounts.unresolved,
+      failed: statusCounts.failed,
+      in_progress: statusCounts.in_progress,
+      orphan_cards: orphanCards,
+      topology: {
+        edge_count: Array.from(allRequires).length,
+        max_fan_out_card: maxFanOut.name,
+        max_fan_out: maxFanOut.fanOut
+      }
+    },
+    cards
+  };
+}
+function cmdStatus(args) {
+  const rgIdx = args.indexOf("--rg");
+  const asJson = args.includes("--json");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  if (!dir) {
+    console.error("Usage: board-live-cards status --rg <dir>");
+    process.exit(1);
+  }
+  const statusOutPath = resolveStatusSnapshotPath(dir);
+  let statusObject;
+  if (fs.existsSync(statusOutPath)) {
+    statusObject = JSON.parse(fs.readFileSync(statusOutPath, "utf-8"));
+  } else {
+    statusObject = buildBoardStatusObject(dir, loadBoard(dir));
+    writeJsonAtomic(statusOutPath, statusObject);
+  }
+  if (asJson) {
+    console.log(JSON.stringify(statusObject, null, 2));
+    return;
+  }
+  console.log(`Board: ${statusObject.meta.board.path}`);
+  console.log(`Tasks: ${statusObject.summary.card_count}`);
+  console.log("");
+  for (const card of statusObject.cards) {
+    const dataKeys = card.provides_runtime.join(", ");
+    console.log(`  ${card.status.padEnd(12)} ${card.name}${dataKeys ? ` \u2014 [${dataKeys}]` : ""}`);
+  }
+  console.log("");
+  console.log(`Schedule: ${statusObject.summary.eligible} eligible, ${statusObject.summary.pending} pending, ${statusObject.summary.blocked} blocked, ${statusObject.summary.unresolved} unresolved`);
+}
+function cmdTaskCompleted(args) {
+  const rgIdx = args.indexOf("--rg");
+  const tokenIdx = args.indexOf("--token");
+  const dataIdx = args.indexOf("--data");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  if (!dir || !token) {
+    console.error("Usage: board-live-cards task-completed --rg <dir> --token <token> [--data <json>]");
+    process.exit(1);
+  }
+  const decoded = decodeCallbackToken2(token);
+  if (!decoded) {
+    console.error("Invalid callback token");
+    process.exit(1);
+  }
+  const data = dataIdx !== -1 ? JSON.parse(args[dataIdx + 1]) : {};
+  writeRuntimeDataObjects(dir, data);
+  appendEventToJournal(dir, {
+    type: "task-completed",
+    taskName: decoded.taskName,
+    data,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  void processAccumulatedEventsForced(dir);
+  console.log("Task completed.");
+}
+function cmdTaskFailed(args) {
+  const rgIdx = args.indexOf("--rg");
+  const tokenIdx = args.indexOf("--token");
+  const errorIdx = args.indexOf("--error");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  const errorMsg = errorIdx !== -1 ? args[errorIdx + 1] : "unknown error";
+  if (!dir || !token) {
+    console.error("Usage: board-live-cards task-failed --rg <dir> --token <token> [--error <message>]");
+    process.exit(1);
+  }
+  const decoded = decodeCallbackToken2(token);
+  if (!decoded) {
+    console.error("Invalid callback token");
+    process.exit(1);
+  }
+  appendEventToJournal(dir, {
+    type: "task-failed",
+    taskName: decoded.taskName,
+    error: errorMsg,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  void processAccumulatedEventsForced(dir);
+  console.log("Task failed.");
+}
+function cmdRemoveCard(args) {
+  const rgIdx = args.indexOf("--rg");
+  const idIdx = args.indexOf("--id");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const cardId = idIdx !== -1 ? args[idIdx + 1] : void 0;
+  if (!dir || !cardId) {
+    console.error("Usage: board-live-cards remove-card --rg <dir> --id <card-id>");
+    process.exit(1);
+  }
+  appendEventToJournal(dir, {
+    type: "task-removal",
+    taskName: cardId,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  void processAccumulatedEventsInfinitePass(dir);
+  console.log(`Card "${cardId}" removed.`);
+}
+function cmdSourceDataFetched(args) {
+  const tmpIdx = args.indexOf("--tmp");
+  const tokenIdx = args.indexOf("--token");
+  const tmpFile = tmpIdx !== -1 ? args[tmpIdx + 1] : void 0;
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  if (!tmpFile || !token) {
+    console.error("Usage: board-live-cards source-data-fetched --tmp <tmp-file> --token <sourceToken>");
+    process.exit(1);
+  }
+  const payload = decodeSourceToken(token);
+  if (!payload) {
+    console.error("Invalid source token");
+    process.exit(1);
+  }
+  const { cbk, rg, cid, b, d } = payload;
+  const destPath = path.join(rg, d);
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+  fs.renameSync(tmpFile, destPath);
+  console.log(`[source-data-fetched] ${cid}.${b} \u2192 ${d}`);
+  const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const cbkDecoded = decodeCallbackToken2(cbk);
+  if (!cbkDecoded) {
+    console.error("Invalid callback token embedded in source token");
+    process.exit(1);
+  }
+  appendEventToJournal(rg, {
+    type: "task-progress",
+    taskName: cbkDecoded.taskName,
+    update: { bindTo: b, fetchedAt, dest: d },
+    timestamp: fetchedAt
+  });
+  void processAccumulatedEventsInfinitePass(rg);
+}
+function cmdSourceDataFetchFailure(args) {
+  const tokenIdx = args.indexOf("--token");
+  const reasonIdx = args.indexOf("--reason");
+  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  const reason = reasonIdx !== -1 ? args[reasonIdx + 1] : "unknown";
+  if (!token) {
+    console.error("Usage: board-live-cards source-data-fetch-failure --token <sourceToken> [--reason <msg>]");
+    process.exit(1);
+  }
+  const payload = decodeSourceToken(token);
+  if (!payload) {
+    console.error("Invalid source token");
+    process.exit(1);
+  }
+  const { cbk, rg, cid, b } = payload;
+  console.log(`[source-data-fetch-failure] ${cid}.${b}: ${reason}`);
+  const cbkDecoded = decodeCallbackToken2(cbk);
+  if (!cbkDecoded) {
+    console.error("Invalid callback token embedded in source token");
+    process.exit(1);
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  appendEventToJournal(rg, {
+    type: "task-progress",
+    taskName: cbkDecoded.taskName,
+    update: { bindTo: b, failure: true, reason },
+    timestamp
+  });
+  void processAccumulatedEventsInfinitePass(rg);
+}
+function cmdRunSources(args) {
+  const cardIdx = args.indexOf("--card");
+  const tokenIdx = args.indexOf("--token");
+  const rgIdx = args.indexOf("--rg");
+  const cardFilePath = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
+  const callbackToken = tokenIdx !== -1 ? args[tokenIdx + 1] : void 0;
+  const boardDir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  if (!cardFilePath || !callbackToken || !boardDir) {
+    console.error("Usage: board-live-cards run-sources-internal --card <path> --token <token> --rg <dir>");
+    process.exit(1);
+  }
+  const card = JSON.parse(fs.readFileSync(cardFilePath, "utf-8"));
+  if (path.basename(cardFilePath).startsWith("card-enriched-")) {
+    try {
+      fs.unlinkSync(cardFilePath);
+    } catch {
+    }
+  }
+  console.log(`[run-sources-internal] Processing card "${card.id}"`);
+  const executorFile = path.join(boardDir, ".task-executor");
+  const taskExecutor = fs.existsSync(executorFile) ? fs.readFileSync(executorFile, "utf-8").trim() : void 0;
+  function runSource(src) {
+    const sourceToken = encodeSourceToken({
+      cbk: callbackToken,
+      rg: boardDir,
+      cid: card.id,
+      b: src.bindTo,
+      d: src.outputFile ?? ""
+    });
+    function reportFailure(reason) {
+      invokeSourceDataFetchFailure(sourceToken, reason, (err) => {
+        if (err) console.error(`[run-sources-internal] source-data-fetch-failure call failed:`, err.message);
+      });
+    }
+    function reportFetched(outFile2) {
+      invokeSourceDataFetched(sourceToken, outFile2);
+    }
+    if (taskExecutor) {
+      if (!src.outputFile) {
+        console.warn(`[run-sources-internal] source "${src.bindTo}" has no outputFile configured \u2014 cannot deliver`);
+        reportFailure("no outputFile configured");
+        return;
+      }
+      const inFile = path.join(os.tmpdir(), `card-source-in-${src.bindTo}-${Date.now()}.json`);
+      const outFile2 = path.join(os.tmpdir(), `card-source-out-${src.bindTo}-${Date.now()}.json`);
+      const errFile = path.join(os.tmpdir(), `card-source-err-${src.bindTo}-${Date.now()}.txt`);
+      const sourceForExecutor = {
+        ...src,
+        cwd: typeof src.cwd === "string" && src.cwd ? src.cwd : path.dirname(cardFilePath || ""),
+        boardDir: typeof src.boardDir === "string" && src.boardDir ? src.boardDir : boardDir
+      };
+      appendTaskExecutorLog(boardDir, sourceForExecutor);
+      fs.writeFileSync(inFile, JSON.stringify(sourceForExecutor, null, 2), "utf-8");
+      console.log(`[run-sources-internal] task-executor: ${taskExecutor} run-source-fetch --in ${inFile} --out ${outFile2} --err ${errFile}`);
+      try {
+        execCommandSync(taskExecutor, ["run-source-fetch", "--in", inFile, "--out", outFile2, "--err", errFile], {
+          shell: true,
+          timeout: src.timeout ?? 12e4
+        });
+      } catch (err) {
+        const reason = err.message ?? String(err);
+        console.error(`[run-sources-internal] task-executor failed for source "${src.bindTo}":`, reason);
+        reportFailure(reason);
+        return;
+      }
+      if (fs.existsSync(outFile2)) {
+        reportFetched(outFile2);
+      } else {
+        const errMsg = fs.existsSync(errFile) ? fs.readFileSync(errFile, "utf-8").trim() : "executor produced no output file";
+        console.warn(`[run-sources-internal] source "${src.bindTo}": ${errMsg}`);
+        reportFailure(errMsg);
+      }
+      return;
+    }
+    if (!src.outputFile) {
+      console.warn(`[run-sources-internal] source "${src.bindTo}" has no outputFile configured \u2014 cannot deliver`);
+      reportFailure("no outputFile configured");
+      return;
+    }
+    const outFile = path.join(os.tmpdir(), `card-source-out-${src.bindTo}-${Date.now()}.json`);
+    if (!src.cli) {
+      const errMsg = "source.cli is required for built-in source execution";
+      console.warn(`[run-sources-internal] source "${src.bindTo}": ${errMsg}`);
+      reportFailure(errMsg);
+      return;
+    }
+    const timeout = src.timeout ?? 12e4;
+    const sourceCwd = typeof src.cwd === "string" ? src.cwd : path.dirname(cardFilePath || "");
+    const sourceBoardDir = typeof src.boardDir === "string" ? src.boardDir : boardDir;
+    const cmdParts = splitCommandLine(src.cli);
+    if (cmdParts.length === 0) {
+      const errMsg = "source.cli command is empty";
+      console.warn(`[run-sources-internal] source "${src.bindTo}": ${errMsg}`);
+      reportFailure(errMsg);
+      return;
+    }
+    const rawCmd = cmdParts[0];
+    const cmd = /^(node|node\.exe)$/i.test(rawCmd) ? process.execPath : rawCmd;
+    const cliArgs = cmdParts.slice(1);
+    let stdout;
+    try {
+      stdout = execCommandSync(cmd, cliArgs, {
+        shell: false,
+        encoding: "utf-8",
+        timeout,
+        cwd: sourceCwd,
+        env: {
+          ...process.env,
+          ...sourceBoardDir ? { BOARD_DIR: sourceBoardDir } : {}
+        }
+      });
+    } catch (err) {
+      const reason = err.message ?? String(err);
+      console.error(`[run-sources-internal] source fetch failed for source "${src.bindTo}":`, reason);
+      reportFailure(reason);
+      return;
+    }
+    fs.writeFileSync(outFile, stdout.trim(), "utf-8");
+    reportFetched(outFile);
+  }
+  const sources = card.sources ?? [];
+  for (const src of sources) {
+    runSource(src);
+  }
+}
+function cmdRunSourceFetch(args) {
+  const inIdx = args.indexOf("--in");
+  const outIdx = args.indexOf("--out");
+  const errIdx = args.indexOf("--err");
+  const inFile = inIdx !== -1 ? args[inIdx + 1] : void 0;
+  const outFile = outIdx !== -1 ? args[outIdx + 1] : void 0;
+  const errFile = errIdx !== -1 ? args[errIdx + 1] : void 0;
+  if (!inFile || !outFile) {
+    console.error("Usage: board-live-cards run-source-fetch --in <source.json> --out <result.json> [--err <error.txt>]");
+    process.exit(1);
+  }
+  if (!fs.existsSync(inFile)) {
+    const msg = `Input file not found: ${inFile}`;
+    if (errFile) fs.writeFileSync(errFile, msg);
+    console.error(`[run-source-fetch] ${msg}`);
+    process.exit(1);
+  }
+  let source;
+  try {
+    const raw = fs.readFileSync(inFile, "utf-8");
+    source = JSON.parse(raw);
+  } catch (err) {
+    const msg = `Failed to parse input file: ${err.message}`;
+    if (errFile) fs.writeFileSync(errFile, msg);
+    console.error(`[run-source-fetch] ${msg}`);
+    process.exit(1);
+  }
+  if (!source.cli) {
+    const msg = "Source definition missing cli field (board-live-cards built-in executor only understands source.cli)";
+    if (errFile) fs.writeFileSync(errFile, msg);
+    console.error(`[run-source-fetch] ${msg}`);
+    process.exit(1);
+  }
+  console.log(`[run-source-fetch] executing: ${source.cli}`);
+  const timeout = source.timeout ?? 12e4;
+  const sourceCwd = typeof source.cwd === "string" ? source.cwd : process.cwd();
+  const sourceBoardDir = typeof source.boardDir === "string" ? source.boardDir : void 0;
+  const cmdParts = splitCommandLine(source.cli);
+  if (cmdParts.length === 0) {
+    const msg = "Source cli command is empty";
+    if (errFile) fs.writeFileSync(errFile, msg);
+    console.error(`[run-source-fetch] ${msg}`);
+    process.exit(1);
+  }
+  const rawCmd = cmdParts[0];
+  const cmd = /^(node|node\.exe)$/i.test(rawCmd) ? process.execPath : rawCmd;
+  const cliArgs = cmdParts.slice(1);
+  let stdout;
+  try {
+    stdout = execCommandSync(cmd, cliArgs, {
+      shell: false,
+      encoding: "utf-8",
+      timeout,
+      cwd: sourceCwd,
+      env: {
+        ...process.env,
+        ...sourceBoardDir ? { BOARD_DIR: sourceBoardDir } : {}
+      }
+    });
+  } catch (err) {
+    const msg = err.message ?? String(err);
+    console.error(`[run-source-fetch] cli failed: ${msg}`);
+    if (errFile) fs.writeFileSync(errFile, msg);
+    process.exit(1);
+  }
+  const result = stdout.trim();
+  try {
+    fs.writeFileSync(outFile, result);
+    console.log(`[run-source-fetch] result written to ${outFile}`);
+  } catch (err) {
+    const msg = `Failed to write output file: ${err.message}`;
+    console.error(`[run-source-fetch] ${msg}`);
+    if (errFile) fs.writeFileSync(errFile, msg);
+    process.exit(1);
+  }
+}
+function cmdUpdateCard(args) {
+  const rgIdx = args.indexOf("--rg");
+  const idIdx = args.indexOf("--card-id");
+  const restart = args.includes("--restart");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const cardId = idIdx !== -1 ? args[idIdx + 1] : void 0;
+  if (!dir || !cardId) {
+    throw new Error("Usage: board-live-cards update-card --rg <dir> --card-id <card-id> [--restart]");
+  }
+  const cardPath = lookupCardPath(dir, cardId);
+  if (!cardPath) {
+    throw new Error(`Card "${cardId}" not found in inventory`);
+  }
+  if (!fs.existsSync(cardPath)) {
+    throw new Error(`Card file not found: ${cardPath}`);
+  }
+  const card = JSON.parse(fs.readFileSync(cardPath, "utf-8"));
+  const taskConfig = liveCardToTaskConfig(card);
+  appendEventToJournal(dir, {
+    type: "task-upsert",
+    taskName: cardId,
+    taskConfig,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  if (restart) {
+    appendEventToJournal(dir, {
+      type: "task-restart",
+      taskName: cardId,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  void processAccumulatedEventsInfinitePass(dir);
+  console.log(`Card "${cardId}" updated${restart ? " (restarted)" : ""}.`);
+}
+function cmdUpsertCard(args) {
+  const rgIdx = args.indexOf("--rg");
+  const cardIdx = args.indexOf("--card");
+  const globIdx = args.indexOf("--card-glob");
+  const cardIdIdx = args.indexOf("--card-id");
+  const restart = args.includes("--restart");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const cardFile = cardIdx !== -1 ? args[cardIdx + 1] : void 0;
+  const cardGlob = globIdx !== -1 ? args[globIdx + 1] : void 0;
+  const requestedCardId = cardIdIdx !== -1 ? args[cardIdIdx + 1] : void 0;
+  if (!dir || !cardFile && !cardGlob || cardFile && cardGlob) {
+    console.error("Usage: board-live-cards upsert-card --rg <dir> (--card <card.json> | --card-glob <glob>) [--card-id <card-id>] [--restart]");
+    process.exit(1);
+  }
+  if (cardGlob && requestedCardId) {
+    console.error("Usage: --card-id may be used only with --card (single file), not with --card-glob");
+    process.exit(1);
+  }
+  const cardFiles = cardFile ? [path.resolve(cardFile)] : resolveCardGlobMatches(cardGlob);
+  if (!cardFile && cardFiles.length === 0) {
+    console.error(`No card files matched glob: ${cardGlob}`);
+    process.exit(1);
+  }
+  const idx = buildCardInventoryIndex(dir);
+  const batchByCardId = /* @__PURE__ */ new Map();
+  const batchByCardPath = /* @__PURE__ */ new Map();
+  const plans = [];
+  const logs = [];
+  for (const absCardPath of cardFiles) {
+    if (!fs.existsSync(absCardPath)) {
+      console.error(`Card file not found: ${absCardPath}`);
+      process.exit(1);
+    }
+    const card = JSON.parse(fs.readFileSync(absCardPath, "utf-8"));
+    if (!card.id) {
+      console.error(`Card JSON must have an "id" field (${absCardPath})`);
+      process.exit(1);
+    }
+    if (requestedCardId && requestedCardId !== card.id) {
+      console.error(
+        `Card id mismatch: --card-id "${requestedCardId}" does not match file id "${card.id}" (${absCardPath})`
+      );
+      process.exit(1);
+    }
+    const seenPathCardId = batchByCardPath.get(absCardPath);
+    if (seenPathCardId && seenPathCardId !== card.id) {
+      console.error(
+        `Upsert rejected: file "${absCardPath}" appears multiple times in batch with conflicting ids ("${seenPathCardId}" vs "${card.id}")`
+      );
+      process.exit(1);
+    }
+    const seenCardPath = batchByCardId.get(card.id);
+    if (seenCardPath && seenCardPath !== absCardPath) {
+      console.error(
+        `Upsert rejected: card id "${card.id}" appears multiple times in batch with conflicting files ("${seenCardPath}" vs "${absCardPath}")`
+      );
+      process.exit(1);
+    }
+    const existingById = idx.byCardId.get(card.id);
+    const existingByPath = idx.byCardPath.get(absCardPath);
+    if (existingByPath && existingByPath.cardId !== card.id) {
+      console.error(
+        `Upsert rejected: file "${absCardPath}" is already mapped to card id "${existingByPath.cardId}", cannot remap to "${card.id}"`
+      );
+      process.exit(1);
+    }
+    if (existingById && existingById.cardFilePath !== absCardPath) {
+      console.error(
+        `Upsert rejected: card id "${card.id}" is already mapped to file "${existingById.cardFilePath}", cannot remap to "${absCardPath}"`
+      );
+      process.exit(1);
+    }
+    batchByCardPath.set(absCardPath, card.id);
+    batchByCardId.set(card.id, absCardPath);
+    plans.push({
+      card,
+      absCardPath,
+      isInsert: !existingById
+    });
+  }
+  for (const plan of plans) {
+    const { card, absCardPath, isInsert } = plan;
+    if (isInsert) {
+      const newEntry = {
+        cardId: card.id,
+        cardFilePath: absCardPath,
+        addedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      appendCardInventory(dir, newEntry);
+      idx.byCardId.set(card.id, newEntry);
+      idx.byCardPath.set(absCardPath, newEntry);
+    }
+    const taskConfig = liveCardToTaskConfig(card);
+    appendEventToJournal(dir, {
+      type: "task-upsert",
+      taskName: card.id,
+      taskConfig,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (restart) {
+      appendEventToJournal(dir, {
+        type: "task-restart",
+        taskName: card.id,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    logs.push(`Card "${card.id}" ${isInsert ? "upserted (inserted)" : "upserted (updated)"}${restart ? " (restarted)" : ""}.`);
+  }
+  void processAccumulatedEventsInfinitePass(dir);
+  if (cardGlob) {
+    console.log(`Upserted ${cardFiles.length} cards from glob: ${cardGlob}${restart ? " (restarted)" : ""}`);
+  } else {
+    console.log(logs[0]);
+  }
+}
+async function cmdTryDrain(args) {
+  const rgIdx = args.indexOf("--rg");
+  const inlineLoop = args.includes("--inline-loop");
+  const boardDir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  if (!boardDir) {
+    console.error("Usage: board-live-cards process-accumulated-events --rg <dir>");
+    process.exit(1);
+  }
+  await processAccumulatedEventsForced(boardDir, { inlineLoop });
+}
+function cmdRetrigger(args) {
+  const rgIdx = args.indexOf("--rg");
+  const taskIdx = args.indexOf("--task");
+  const dir = rgIdx !== -1 ? args[rgIdx + 1] : void 0;
+  const taskName = taskIdx !== -1 ? args[taskIdx + 1] : void 0;
+  if (!dir || !taskName) {
+    console.error("Usage: board-live-cards retrigger --rg <dir> --task <task-name>");
+    process.exit(1);
+  }
+  appendEventToJournal(dir, {
+    type: "task-restart",
+    taskName,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  void processAccumulatedEventsInfinitePass(dir);
+  console.log(`Task "${taskName}" retriggered.`);
+}
+async function cli(argv) {
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  switch (cmd) {
+    case "help":
+    case "--help":
+    case "-h":
+      return cmdHelp();
+    case "init":
+      return cmdInit(rest);
+    case "status":
+      return cmdStatus(rest);
+    case "add-cards":
+      return cmdAddCards(rest);
+    case "update-card":
+      return cmdUpdateCard(rest);
+    case "upsert-card":
+      return cmdUpsertCard(rest);
+    case "remove-card":
+      return cmdRemoveCard(rest);
+    case "retrigger":
+      return cmdRetrigger(rest);
+    case "task-completed":
+      return cmdTaskCompleted(rest);
+    case "task-failed":
+      return cmdTaskFailed(rest);
+    case "source-data-fetched":
+      return cmdSourceDataFetched(rest);
+    case "source-data-fetch-failure":
+      return cmdSourceDataFetchFailure(rest);
+    case "run-sources-internal":
+      return cmdRunSources(rest);
+    case "run-source-fetch":
+      return cmdRunSourceFetch(rest);
+    case "process-accumulated-events":
+      return await cmdTryDrain(rest);
+    default:
+      throw new Error(`Unknown command: ${cmd ?? "(none)"}`);
+  }
+}
+function cmdHelp() {
+  console.log(`
+board-live-cards-cli \u2014 LiveCards board CLI
+
+USAGE
+  board-live-cards-cli <command> [options]
+
+BOARD MANAGEMENT
+  init <dir> [--task-executor <script>] [--runtime-out <dir>]
+    Create a new board in <dir>.
+    If --task-executor is given, writes <dir>/.task-executor with the script path.
+    Writes <dir>/.runtime-out (default: <dir>/runtime-out).
+    Published runtime files:
+      <runtime-out>/board-livegraph-status.json
+      <runtime-out>/cards/<card-id>.computed.json
+    Re-running init on an existing board is safe; --task-executor updates the registration.
+
+  status --rg <dir> [--json]
+    Read and print the published status snapshot from <runtime-out>/board-livegraph-status.json.
+    --json emits the stable machine-readable status object.
+
+CARD MANAGEMENT
+  add-cards --rg <dir> (--card <card.json> | --card-glob <glob>)
+    Add one card or many cards from a glob and trigger processing.
+    --card adds one JSON file.
+    --card-glob adds all matching files in deterministic order.
+    Example glob: "examples/browser/boards/portfolio-tracker/cards/*.json"
+
+  update-card --rg <dir> --card-id <card-id> [--restart]
+    Re-read the card JSON from disk and patch the board.
+    --restart clears the task so it re-triggers from scratch.
+
+  upsert-card --rg <dir> (--card <card.json> | --card-glob <glob>) [--card-id <card-id>] [--restart]
+    Insert or update one or many cards.
+    Enforces strict one-to-one mapping between card id and file path:
+      - same id + same file path: update
+      - new id + new file path: insert
+      - id remap or file remap: rejected
+    If --card-id is provided, it must match the id inside the file.
+    --card-id is valid only with --card (single file), not with --card-glob.
+    --restart clears the task so it re-triggers from scratch.
+
+  remove-card --rg <dir> --id <card-id>
+    Remove a card and its task from the board.
+
+  retrigger --rg <dir> --task <task-name>
+    Mark a task not-started and drain to re-trigger it.
+
+TASK CALLBACKS  (called by task executor scripts)
+  task-completed --token <callbackToken> [--data <json>]
+    Signal successful task completion with optional JSON result data.
+
+  task-failed --token <callbackToken> [--error <message>]
+    Signal task failure with an optional error message.
+
+SOURCE CALLBACKS  (called internally by run-sources-internal)
+  source-data-fetched --tmp <file> --token <sourceToken>
+    Atomically rename <file> into the outputFile destination and record delivery
+    in runtime.json. Appends a task-progress event to re-invoke the card handler.
+
+  source-data-fetch-failure --token <sourceToken> [--reason <message>]
+    Record a source fetch failure in runtime.json and append a task-progress event.
+
+INTERNAL COMMANDS
+  process-accumulated-events --rg <dir>
+    Executes forced drain for this board.
+    This command is also used as the background relay worker.
+    By default it schedules a detached worker and returns quickly.
+    Internal workers run with --inline-loop to perform the settle loop.
+
+    Eventual-progress guarantee is relay-based (not per-call blocking guarantee):
+    1) at least one runner continues processing,
+    2) no crash/forced exit in relay window,
+    3) lock stays healthy,
+    4) event production eventually quiesces.
+
+  run-sources-internal-internal --card <card.json> --token <callbackToken> --rg <dir>
+    Execute all source[] entries for a card, then report delivery or failure.
+    (Internal command \u2014 invoked by the card-handler. Not intended for direct use.)
+
+    If <dir>/.task-executor exists, invokes it with run-source-fetch subcommand:
+      <executor> run-source-fetch --in <source_json> --out <outfile> --err <errfile>
+    
+    If no .task-executor is registered, uses board-live-cards built-in run-source-fetch.
+
+  run-source-fetch --in <source.json> --out <result.json> [--err <error.txt>]
+    Execute a source definition. Board-live-cards reads source.cli and executes it.
+    Writes result to --out. Presence of --out after exit indicates success.
+
+RUN-SOURCE-FETCH PROTOCOL
+  External task-executors implement:
+    <executor> run-source-fetch --in <source.json> --out <result.json> [--err <error.txt>]
+
+  INPUT:   --in file contains the full sources[x] definition object
+  OUTPUT:  --out file is written with the result to signal success.
+           --err file may be written to explain failure.
+           
+  Exit code and --out presence determine success:
+    Exit 0 + --out file present \u2192 source delivery recorded, card re-evaluated.
+    Exit non-zero OR --out absent \u2192 source-data-fetch-failure recorded.
+
+BOARD-LIVE-CARDS BUILT-IN EXECUTOR
+  Understands source.cli field only:
+    "sources": [{ "cli": "node ../fetch-prices.js", "bindTo": "prices", "outputFile": "prices.json" }]
+    
+  The source.cli command is executed with:
+    - Direct command invocation (no shell; quote-aware argument parsing)
+    - Stdout is captured and delivered to the card as-is
+    - Timeout from source.timeout (default 120s)
+    
+  The source.cli command must:
+    - Execute successfully (exit 0)
+    - Write output to stdout
+    - Complete within the timeout
+    
+  The output format is the concern of the card's compute function to interpret.
+    
+  External task-executors can interpret source definitions however they want.
+
+EXAMPLES
+  board-live-cards-cli init ./my-board
+  board-live-cards-cli init ./my-board --task-executor ./executors/my-runner.py
+  board-live-cards-cli add-cards --rg ./my-board --card cards/prices.json
+  board-live-cards-cli status --rg ./my-board
+  board-live-cards-cli retrigger --rg ./my-board --task price-fetch
+`.trimStart());
+}
+var isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
+if (isMain) {
+  cli(process.argv.slice(2)).catch((err) => {
+    const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+    console.error(msg);
+    process.exit(1);
+  });
+}
+
+export { BoardJournal, appendCardInventory, appendEventToJournal, buildCardInventoryIndex, cli, createBoardReactiveGraph, decodeSourceToken, encodeSourceToken, getUndrainedEntries, initBoard, liveCardToTaskConfig, loadBoard, loadBoardEnvelope, lookupCardPath, processAccumulatedEvents, processAccumulatedEventsForced, processAccumulatedEventsInfinitePass, readCardInventory, saveBoard, withBoardLock };
+//# sourceMappingURL=board-live-cards-cli.js.map
+//# sourceMappingURL=board-live-cards-cli.js.map